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.

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

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:

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 - Environments, rate limits, and a quick-start walkthrough

• Core Concepts - Data model and lifecycle