Authenticate with the KODE API

The KODE API uses OAuth 2.0 client credentials with a signed JSON Web Token (JWT) client assertion. Your service proves its identity with a private key instead of sending a reusable secret.

How authentication works

Sign a short-lived JWT client assertion with the private key registered for your client ID.
Exchange the assertion for an access token at the token endpoint.
Send the access token in the Authorization header of each API request.
Request a new token before the current one expires.

Keep private keys in an approved secrets manager. Never place private keys or access tokens in browser code, mobile apps, logs, or source control.

Get your credentials

You receive a client ID with your KODE project delivery. Contact your KODE project team if you have a client ID but cannot locate the matching private key.

The exact client assertion claims and credential retrieval steps are being finalized. Until then, follow the instructions supplied with your project delivery.

Create a client assertion

Sign the assertion with your private key, following the JWT bearer profile in RFC 7523. Create a new, short-lived assertion for each token request. To confirm supported signing algorithms, call Get authorization server metadata. This endpoint does not require authentication.

Request an access token

Send the assertion to Create an access token as form data:

curl --fail-with-body \
  --request POST "https://api.kodelabs.com/oauth2/v1/token" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=bms" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=${KODE_CLIENT_ASSERTION}"

The response includes access_token and expires_in. Use the returned lifetime instead of assuming a fixed value.

Use the token

Send the token as a Bearer token:

Authorization: Bearer <access-token>

To try endpoints in the browser, paste the token into the Authorization field of any API reference page.

Renew and revoke tokens

Cache the token and reuse it until it nears expiration, then request a new one. When multiple service instances share one client ID, coordinate renewals so each instance does not request its own token. If a token is exposed, call Revoke an access token with a new client assertion.

Resolve authentication errors

Response	Cause	Fix
`401` from the token endpoint	The assertion is expired, malformed, or signed with the wrong key.	Check the assertion lifetime, audience, and signing algorithm.
`401` from the API	The access token is missing, invalid, or expired.	Request a new access token.
`403` from the API	The service account lacks permission for the building or operation.	Ask your KODE project team to update the service account permissions.

Get started

Guides

API reference

How authentication works

Get your credentials

Create a client assertion

Request an access token

Use the token

Renew and revoke tokens

Resolve authentication errors

​How authentication works

​Get your credentials

​Create a client assertion

​Request an access token

​Use the token

​Renew and revoke tokens

​Resolve authentication errors

How authentication works

Get your credentials

Create a client assertion

Request an access token

Use the token

Renew and revoke tokens

Resolve authentication errors