If you do not yet have your client-id, client-secret or scopes, please refer to the obtain access section to request your credentials before coming back to this step.

# Authorize

Now that you have your API access credentials, you will be able to use your secure backend application to obtain a JSON Web Token, which will be used to authenticate your access to the API.

Note: Clients must maintain proper confidentiality of their credentials as per proper OAuth 2.0 standards (opens new window) (e.g., implemented on a secure server with restricted access to the client credentials). The credentials must NOT be visible to users in any way. Because of this, client side scripting such as javascript will result in an authentication error and a middleware proxy will be required.

# Request a JWT

All endpoints require a JWT which is provisioned using the OAuth 2.0 client credentials workflow (opens new window). To obtain a JWT, you must request one from the /oauth2/token endpoint. You will need to authenticate the request with all of your client credentials.

The following request is authenticated using Open API 3 Basic Auth. Replace the base 64 encoded string in the example below dGVzdF9jbGllbnRfaWQ6dGVzdF9jbGllbnRfc2VjcmV0 with a base 64 encoded string of your credentials"client_id:client_secret".

# Sample request:

# Sample response:

{
  "access_token": "test_token_eyJraWQiOiJZR0FPbnQzNFJhdmFwcFFsNlVRS1I5N215Q0FTM1phdEpxYmRQNG1UQ0xFPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI2ZTFzbWtmaG5jbTdhN3BvZzIyMDc3aTg2dSIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYmVuZXZpdHlcL2FwaSIsImF1dGhfdGltZSI6MTYyMTM1OTUxNywiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfRUdEMnVsRjA1IiwiZXhwIjoxNjIxMzYzMTE3LCJpYXQiOjE2MjEzNTk1MTcsInZlcnNpb24iOjIsImp0aSI6IjU3ZDY1ODYzLTFiZDctNDg0ZC1iNzMxLWJjMDY4MDJhMzkwNyIsImNsaWVudF9pZCI6IjZlMXNta2ZobmNtN2E3cG9nMjIwNzdpODZ1In0.",
  "expires_in": 3600,
  "token_type": "Bearer"
}

You will need to securely store your access_token, as it will be needed to make any further requests to our APIs.

Note: The token is valid for 3600 seconds (1 hour).

Tokens must be reused in an application lifecycle and only re-obtained when they are near expiry to optimize performance, mitigate security risks, and avoid potential rate limits when obtaining tokens. Please refrain from obtaining a token on each call to the API.

You can use "expires_in" response attribute (shown in the sample response above) to determine when a token should be re-obtained. Calculate token expiry time based on the time the authorization request was made (in seconds), adding the response.body.expries_in (also in seconds).

When accessing the API, if the current time is before the expiry time then reuse the token, else request a new token.

Please check our Authentication Errors page if you receive any errors while obtaining your token.

# Using your JWT

The JWT that's returned is a Bearer Token (opens new window), and should be attached as an Authorization header on subsequent requests.

Remember: Reuse the access_token if the current time is before the token expiry time.

# 🚀 ☀️ ⭐️ Congratulations! ⭐️ ☀️ 🚀

Now that you've acquired access to our API, you can proceed to the next step in the process - searching for a cause.

← Obtaining Access Search for a Cause →