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).
Accessing the GlobalGiving REST interface requires an API Key.
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 the cURL program:
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.