API Authentication And Authorization

The transmission of all API requests and responses need to be made over HTTPS (Hypertext Transfer Protocol over Secure Socket Layer - SSL).

API Key

Accessing the GlobalGiving REST interface requires an API Key.

• Users need to obtain an API Key from GlobalGiving. An API Key is a unique key, e.g. api_key = YOUR_API_KEY, assigned to users registered with the system.
• API Keys are long-lived and tied to a user account on the system. Every request will require the submission of an API Key in some form, either in the XML or JSON data request or on the query string so as to identify the user.

Access Tokens

Access tokens are similar to session tokens and allow entering of credentials once per session.

NOTE: Credentials used to receive an access token are the same credentials used when signing up for an API Key. That is, the email and password associated with the new or existing GlobalGiving account used to request an API Key.

Once authenticated, a user is provided with an access token that is submitted with every secure request (those containing '/secure/' in the URL path, e.g. submitting a donation) instead of always submitting a username and password. Access tokens are short-lived and can expire so users need to re-GET a token at the start of each session or if their current access token expires. Note that access token timeouts are individually set for each API user as a database configuration and by default are set to 10 hours.

Sample XML request for an acess_token by making a POST to '/api/userservice/tokens' as shown below using cURL:

Access Token Request

curl -H "Accept: application/xml" -H "Content-Type: application/xml" -d "<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<auth_request>
   <user>
      <email>John_Doe@hotmail.com</email>
      <password>somepassword</password>
   </user>
   <api_key>YOUR_API_KEY</api_key>
</auth_request>" -X POST https://api.globalgiving.org/api/userservice/tokens

NOTE: Above XML request has carriage returns for readability.

Access Token Response

<?xml version="1.0" encoding="UTF-8"? standalone="yes">
<auth_response>
  <access_token>u28wgo0aq04bzxy90aq1q6wttx0aq2cfelvw0aq3</access_token>
</auth_response>

The "u28wgo0aq04bzxy90aq1q6wttx0aq2cfelvw0aq3" in the response above is the token string that would be used in subsequent secure requests.