# Get an access token

URL: https://docs.sparklayer.io/developers/api/core/get-an-access-token
Operation: `POST /api/auth/token` (operationId `getAccessToken`)
OpenAPI spec: https://docs.sparklayer.io/openapi/core.yaml

Exchanges an API key's Client ID and Client Secret for an access token (the OAuth 2.0 client credentials grant). Send the credentials as JSON with `Content-Type: application/json`: the endpoint doesn't accept a form-encoded body, so standard OAuth 2.0 client libraries won't work. Send the token as `Authorization: Bearer <access_token>`, with the same `Site-Id` header, on every other request.

Tokens are valid for 3,600 seconds (`expires_in`), and only for the Site ID and environment (live or test) they were issued for. There's no refresh token: cache the token and request a new one shortly before it expires. Create API keys in the SparkLayer Dashboard under **Settings > API**; deleting a key revokes its tokens. See [Authentication](https://docs.sparklayer.io/developers/authentication.md).

`POST /api/auth/token`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** none: this endpoint issues the access token. See [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/auth/token" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}'
```

Set `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `grant_type` | "client_credentials" | Yes | Always `client_credentials`. |
| `client_id` | string | Yes | The Client ID shown when you created the API key. |
| `client_secret` | string | Yes | The Client Secret shown when you created the API key. |

```json
{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
```

### Responses

#### 200: The access token.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token_type` | "Bearer" | Yes | Always `Bearer`. |
| `expires_in` | integer | Yes | Seconds until the token expires: tokens are valid for 1 hour. |
| `access_token` | string | Yes | The token to send in the `Authorization: Bearer <access_token>` header. It only works with the Site ID and environment it was issued for. |

```json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ5b3VyLWNsaWVudC1pZCJ9.c2lnbmF0dXJl"
}
```

#### 400: The `Site-Id` header, a required field or `Content-Type: application/json` is missing (`invalid_request`), or `grant_type` isn't `client_credentials` (`unsupported_grant_type`).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | "invalid_request" \| "unsupported_grant_type" \| "invalid_client" | Yes | `invalid_request`: a required field is missing. `unsupported_grant_type`: `grant_type` isn't `client_credentials`. `invalid_client`: the client ID or secret is wrong, the key has been deleted, or it belongs to the other environment. |
| `status` | integer | Yes | The HTTP status code. |
| `detail` | string | Yes | A human-readable explanation, for logging and debugging. |

```json
{
  "title": "unsupported_grant_type",
  "status": 400,
  "detail": "The authorization grant type is not supported"
}
```

#### 401: The client ID or secret is wrong, the key has been deleted, or it belongs to the other environment (`invalid_client`).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | "invalid_request" \| "unsupported_grant_type" \| "invalid_client" | Yes | `invalid_request`: a required field is missing. `unsupported_grant_type`: `grant_type` isn't `client_credentials`. `invalid_client`: the client ID or secret is wrong, the key has been deleted, or it belongs to the other environment. |
| `status` | integer | Yes | The HTTP status code. |
| `detail` | string | Yes | A human-readable explanation, for logging and debugging. |

```json
{
  "title": "invalid_client",
  "status": 401,
  "detail": "Client authentication failed"
}
```