> This is the Markdown of https://backed.giving/developers/reference/authentication, a page of the Backed developer documentation. Every page is listed at https://backed.giving/developers/llms.txt.

# Authentication

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

- [POST /oauth/token](#issueOAuthToken) — 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](https://backed.giving/developers/guides/authentication.md).

<a id="issueOAuthToken"></a>
## 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:

```bash
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:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `grant_type` | `string` | Yes | Always `client_credentials`. |
| `client_id` | `string` | No | Your Client ID |
| `client_secret` | `string` | No | Your Client Secret |

Example request body:

```text
grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret
```

<a id="issueOAuthToken-200"></a>
### 200 response

Token issued. Shown once; never cached.

Headers: `Cache-Control`.

Fields of TokenResponse:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `access_token` | `string` | Yes |  |
| `token_type` | `string` | Yes | Always `Bearer`. |
| `expires_in` | `number` | Yes |  |
| `created_at` | `integer` | Yes |  |

Example 200 response:

```json
{
  "access_token": "q3Vx9LmT2sKp4Rz7Wn1YeB8cD5fG6hJ0kN_aQ-uIoPr",
  "token_type": "Bearer",
  "expires_in": 432000,
  "created_at": 1762650000
}
```

<a id="issueOAuthToken-400"></a>
### 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:

```json
{
  "error": "invalid_request",
  "error_description": "Missing required parameter: grant_type"
}
```

Example 400 response: unsupported_grant_type:

```json
{
  "error": "unsupported_grant_type",
  "error_description": "Only client_credentials is supported"
}
```

<a id="issueOAuthToken-401"></a>
### 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:

```json
{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}
```

<a id="issueOAuthToken-403"></a>
### 403 response

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

Example 403 response:

```json
{
  "error": "https_required"
}
```

<a id="issueOAuthToken-404"></a>
### 404 response

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

Example 404 response:

```json
{
  "error": "not_found"
}
```

<a id="issueOAuthToken-429"></a>
### 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:

```json
{
  "error": "rate_limited",
  "error_description": "Too many requests"
}
```

<a id="issueOAuthToken-500"></a>
### 500 response

An unexpected server error.

Example 500 response:

```json
{
  "error": "server_error"
}
```

<a id="issueOAuthToken-503"></a>
### 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:

```json
{
  "error": "temporarily_unavailable"
}
```