> For the complete documentation index, see [llms.txt](https://api-docs.flagstoneim.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.flagstoneim.com/authentication.md).

# Authentication

You'll need both an API key and an OAuth 2.0 access token for every API call.

***

## API Key

Include your subscription key in the `cdpapi-Subscription-Key` header on every request.

```http
GET /products/ HTTP/1.1
Host: api.sandbox.flagstoneim.com
cdpapi-Subscription-Key: your-api-key-here
```

We issue sandbox and production keys separately during onboarding. Keep your key secret and never embed it in client-side code.

***

## OAuth 2.0 Client Credentials

You also authenticate with OAuth 2.0 using the client credentials grant. You exchange a `client_id` and `client_secret` for a short-lived access token, then pass that token as a Bearer header on every API call.

### 1. Get an Access Token

```http
POST /connect/token HTTP/1.1
Host: auth.flagstoneim.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
```

You'll get back an `access_token` and its lifetime in seconds (`expires_in`).

We'll exchange your `client_id` and `client_secret` securely before your integration goes live. Store the secret in a secrets manager or vault. Never log or transmit it beyond this token request.

### 2. Call APIs with the Token

Include the `access_token` as a Bearer token in the `Authorization` header:

```http
POST /example HTTP/1.1
Host: api.flagstoneim.com
Authorization: Bearer {access_token}
Content-Type: application/json
```

### 3. Token Renewal

Access tokens expire. You've got two renewal strategies:

| Strategy        | How                                                                                             |
| --------------- | ----------------------------------------------------------------------------------------------- |
| **Pre-emptive** | Track `expires_in` from the token response. Request a new token before the current one expires. |
| **Reactive**    | If an API call returns `401 Unauthorized`, request a new token and retry the call.              |

Renewing pre-emptively avoids a failed call on every token expiry. We'd recommend combining both: renew ahead of expiry, but handle `401` as a fallback.

### Request Access Token Sequence

<figure><img src="/files/RiigVrlPDwnzo7ws3L5b" alt="Request new token Flow"><figcaption></figcaption></figure>

### Token Renewal Sequence

<figure><img src="/files/wQpJNGQDG9l5TS6ktkr6" alt="Refresh token Flow"><figcaption></figcaption></figure>

***

## Next Steps

* [Getting Started](/getting-started.md) - Environments, rate limits, and a quick-start walkthrough
* [Core Concepts](/core-concepts.md) - Data model and lifecycle