Authentication

Every request to the Diversity Sync API must be authenticated. Authentication is an OAuth2 client-credentials flow: you create a long-lived API key in the admin panel, exchange it for a short-lived access token, then send that token as a bearer token on each request.

Create an API key

API keys are created in your Diversity Sync workspace under Admin → API Keys by a user with the write:api_keys permission. When you create a key you choose its scopes — the set of read: / write: permissions it carries — which can never exceed the permissions of the staff member who creates it.

A key is shown only once, at creation, and looks like this:

An API key

ds_live_2f1ac3…d0b1_9c4e7a…ab12

Store the key somewhere safe the moment it's created — for security it is never shown again. A key is tied to the staff member who created it and is automatically revoked if that staff member is archived.

POST/oauth/token

Exchange the key for an access token

Keys are never sent to the resource endpoints directly. Instead, exchange your key for a short-lived access token at the token endpoint, then use that token on /v1 requests. Tokens are valid for 15 minutes (expires_in is in seconds); request a new one when it expires.

Present the key in the Authorization header as a bearer credential (or in a JSON key body field).

Response attributes

Name
access_token
Type
string
Description
The bearer token to send on subsequent /v1 requests.
Name
token_type
Type
string
Description
Always Bearer.
Name
expires_in
Type
integer
Description
Token lifetime in seconds (900 = 15 minutes).
Name
scope
Type
string
Description
Space-delimited list of the scopes granted to this token.

Request

POST

/oauth/token

curl https://api.diversitysync.com/oauth/token \
  -H "Authorization: Bearer ds_live_2f1ac3…d0b1_9c4e7a…ab12"

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "read:users read:participants"
}

Make authenticated requests

Send the access token as a bearer token in the Authorization header on every /v1 request:

Example request with bearer token

curl https://api.diversitysync.com/v1/staff \
  -H "Authorization: Bearer {access_token}"

If the token is missing, expired, or the underlying key has been revoked, the API responds with 401 Unauthorized — exchange your key for a fresh token and try again. A request whose token lacks the required scope returns 403 Forbidden.