> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate with the KODE API

> Use OAuth 2.0 client credentials and signed JWT assertions to authenticate KODE API requests.

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

```mermaid actions={false} theme={"theme":{"light":"github-light","dark":"github-dark"}}
%%{init: {"theme": "neutral"}}%%
sequenceDiagram
    participant Service as Your service
    participant Auth as KODE authorization server
    participant API as KODE API

    Service->>Service: Sign client assertion with private key
    Service->>Auth: POST /oauth2/v1/token
    Auth-->>Service: Bearer access token
    Service->>API: Request with Authorization header
    API-->>Service: JSON response
```

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

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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](https://datatracker.ietf.org/doc/html/rfc7523). Create a new, short-lived assertion for each token request.

To confirm supported signing algorithms, call [Get authorization server metadata](https://docs.kodelabs.com/products/kode-api/api-reference/authentication/get-authorization-server-metadata.md). This endpoint does not require authentication.

## Request an access token

Send the assertion to [Create an access token](https://docs.kodelabs.com/products/kode-api/api-reference/authentication/create-an-access-token.md) as form data:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer <access-token>
```

To try endpoints in the browser, paste the token into the `Authorization` field of any [API reference](https://docs.kodelabs.com/products/kode-api/api-reference/introduction.md) 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](https://docs.kodelabs.com/products/kode-api/api-reference/authentication/revoke-an-access-token.md) 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.