> 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
### Token Renewal Sequence
***
## Next Steps
* [Getting Started](/getting-started.md) - Environments, rate limits, and a quick-start walkthrough
* [Core Concepts](/core-concepts.md) - Data model and lifecycle
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://api-docs.flagstoneim.com/authentication.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.