Guides

Authentication

The Kordiam API uses OAuth2 client credentials for token issuance. Protected resource endpoints use JWT bearer authentication. /api/v2/auth/token and /api/v2/auth/refresh are the bootstrap endpoints for obtaining and rotating tokens. They are public bootstrap endpoints and do not require a bearer token themselves.

API Credentials

Generate, refresh, or delete your API credentials (client ID and client secret) on the API credentials page in the Kordiam app. These credentials let other systems (such as a CMS) access Kordiam.

Obtaining a Token

Response


Response
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.read api.write",
  "refresh_token": "dGhpcyBpcyBh..."
}

Schedule refresh from expires_in

Save the returned access_token and use the returned expires_in value when scheduling refresh logic instead of assuming a fixed token lifetime.

Using the Token

Include the token in the Authorization header of every API request:

Code
Authorization: Bearer eyJhbGciOi...

Refreshing a Token

Use the refresh token to obtain a new access token before the current one expires:

Refresh a token
curl -X POST https://api.kordiam.app/api/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "dGhpcyBpcyBh..."
  }'

Response


Response
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.read api.write",
  "refresh_token": "bmV3IHJlZnJlc2g..."
}

Refresh tokens are single-use

Each refresh returns a new refresh_token, and the token you sent stops working. Always store the refresh_token from the latest response and use it for the next refresh — reusing a spent refresh token fails with 401 unauthorized.

Token Lifetime

Use the expires_in value from the response instead of hard-coding an access-token lifetime.
Refresh tokens are single-use: every /api/v2/auth/refresh call returns a new refresh_token that replaces the previous one.
Use the API reference as the source of truth for the exact request and response contract.

Error Responses

Status	Error Type	Description
401	unauthorized	Invalid client credentials, refresh token, or bearer token
401	token-revoked	Bearer token has been revoked

Last modified on June 24, 2026

Versioning

Obtaining a Token

curl -X POST https://api.kordiam.app/api/v2/auth/token \
-H "Content-Type: application/json" \
-d '{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "grant_type": "client_credentials"
}'

Response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.read api.write",
  "refresh_token": "dGhpcyBpcyBh..."
}

Schedule refresh from expires_in

Save the returned access_token and use the returned expires_in value when scheduling refresh logic instead of assuming a fixed token lifetime.

Refreshing a Token

Use the refresh token to obtain a new access token before the current one expires:

Refresh a token

curl -X POST https://api.kordiam.app/api/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "dGhpcyBpcyBh..."
  }'

Response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.read api.write",
  "refresh_token": "bmV3IHJlZnJlc2g..."
}

Refresh tokens are single-use

Token Lifetime

Use the expires_in value from the response instead of hard-coding an access-token lifetime.

Refresh tokens are single-use: every /api/v2/auth/refresh call returns a new refresh_token that replaces the previous one.

Use the API reference as the source of truth for the exact request and response contract.

Status

Error Type

Description

401

unauthorized

Invalid client credentials, refresh token, or bearer token

401

token-revoked

Bearer token has been revoked