Authentication and API keys

The Kardinal API authenticates every request with a JWT access_token, sent as a bearer token. This guide covers how to obtain one, keep it valid, store it safely, and what to do when authentication fails.

Kardinal currently provisions access by inviting a user (typically your company email) to set a password on an environment such as https://<env>.kardinal.ai — there is no separate, long-lived “API key” to generate from a dashboard. Your username/password pair is what’s exchanged for short-lived tokens below. If your integration needs a different credential model (e.g. a dedicated service account), raise it with your Account Executive.

Obtain an access token

curl -X POST "https://<env>.kardinal.ai/api/v2/login" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"username":"<username>","password":"<password>"}'

Response

{
  "access_token": "<token>",
  "refresh_token": "<refresh_token>",
  "user": { ... }
}

Send the access_token on every request:

Authorization: Bearer <access_token>

Token lifetime and refresh

An access_token is valid for one hour. This short lifetime limits the damage of a leaked token, but it means your integration must refresh proactively rather than waiting for a request to fail:

Call the login endpoint again, or
Use the refresh_token you received at login against the refreshToken endpoint to get a new access_token without re-sending the password.

A practical pattern is to refresh a few minutes before the hour is up (e.g. on a 50-minute timer), so requests never race against expiry.

Storing credentials

Treat the username/password and any live access_token / refresh_token like any other production secret:

Store them in environment variables or a secrets manager (Vault, AWS/GCP/Azure secret managers, etc.) — never hard-code them in source control.
Keep sandbox and production credentials in separate secrets, scoped to separate deployment environments.
Log requests without the Authorization header value; if you need to debug a 401, log the response body, not the token.
If a password or refresh token is suspected to be compromised, contact your Kardinal support channel (api@kardinal.ai or your Account Executive) to have access reset — there is no documented self-service revocation endpoint at this time.

Common authentication issues

Symptom	Likely cause	What to do
Requests start failing after ~1 hour of otherwise working fine	`access_token` expired	Refresh via `refreshToken` (or re-login) before the hour mark, proactively
Every request fails immediately, including the first one	Wrong `username`/`password`, or wrong `<env>` host	Re-check credentials and the environment URL you were given at onboarding
Requests fail with no `Authorization` header sent	Header missing or malformed	Confirm the header is exactly `Authorization: Bearer <access_token>` (note: some internal examples in older docs use `Authorisation` — the standard spelling `Authorization` is what the API expects)

Exact HTTP status codes and error bodies for these cases will be documented in Error codes once confirmed against the live API.

Integration

Advanced modeling

Authentication and API keys

Obtain an access token

Token lifetime and refresh

Storing credentials

Common authentication issues

​Obtain an access token

​Token lifetime and refresh

​Storing credentials

​Common authentication issues

Obtain an access token

Token lifetime and refresh

Storing credentials

Common authentication issues