Skip to main content

Developers · Reference

Authentication

Exchange a credential for an access token. 1 operation: parameters, request body and answers, with examples.

  • POST /oauth/token — Obtain an access token with the OAuth 2.0 client-credentials grant.

How to use the token, and what each scope opens, is in the Authentication guide.

POST /oauth/token

Obtain an access token with the OAuth 2.0 client-credentials grant.

Form-encoded body; client_id and client_secret may instead be sent with HTTP Basic authentication. Each success issues a new token valid 432000 seconds (5 days). Throttled to 30 requests a minute per client_id, counted before the secret is checked.

  • Operation ID: issueOAuthToken
  • Authentication: No token: the credential’s client_id and client_secret, in the form body or with HTTP Basic authentication.
Example request
curl -X POST "https://your-org.backed.giving/oauth/token" \
  -d grant_type=client_credentials \
  -d client_id=your-client-id \
  -d client_secret=your-client-secret

Request body

application/x-www-form-urlencoded, the TokenRequest schema. client_id and client_secret are required unless sent with HTTP Basic authentication.

Fields of the TokenRequest body
FieldTypeRequiredNotes
grant_typestringYesAlways client_credentials.
client_idstringNoYour Client ID
client_secretstringNoYour Client Secret
Example request body
grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret

200 response

Token issued. Shown once; never cached.

Headers: Cache-Control.

Fields of TokenResponse
FieldTypeRequiredNotes
access_tokenstringYes
token_typestringYesAlways Bearer.
expires_innumberYes
created_atintegerYes
Example 200 response
{
  "access_token": "q3Vx9LmT2sKp4Rz7Wn1YeB8cD5fG6hJ0kN_aQ-uIoPr",
  "token_type": "Bearer",
  "expires_in": 432000,
  "created_at": 1762650000
}

400 response

invalid_request: A query parameter is invalid, or a write’s body is not a JSON object. unsupported_grant_type: The grant type is not client_credentials.

Headers: Cache-Control.

Example 400 response: invalid_request
{
  "error": "invalid_request",
  "error_description": "Missing required parameter: grant_type"
}
Example 400 response: unsupported_grant_type
{
  "error": "unsupported_grant_type",
  "error_description": "Only client_credentials is supported"
}

401 response

Client authentication failed: an unknown client_id, a wrong secret, a revoked credential or another Organisation’s, or API access is not Full.

Headers: Cache-Control.

Example 401 response
{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

403 response

The request was sent over plain HTTP and was not processed.

Example 403 response
{
  "error": "https_required"
}

404 response

An unknown host or path, or an id that is unknown, deleted or of another Organisation.

Example 404 response
{
  "error": "not_found"
}

429 response

A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client_id.

Headers: Retry-After.

Example 429 response
{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

500 response

An unexpected server error.

Example 500 response
{
  "error": "server_error"
}

503 response

The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds.

Headers: Retry-After.

Example 503 response
{
  "error": "temporarily_unavailable"
}