API authentication: bearer tokens, scopes, and 401s

The Platform API lives at https://api.kiteml.com/v1 and authenticates every request with an API key.

Create a key

Create a key from Platform API → API keys in the dashboard. Scope it to what the key actually does — augmentations if you only generate datasets, training runs if you only train.

Keys start with kite_ and are shown only once, at creation time. Store the value in a secret manager or environment variable — you can’t retrieve it later, only revoke it and create a new one.

Authenticate a request

Send the key in the Authorization header as a Bearer token on every request.

export KITE_API_KEY=kite_aBcDeFgH...

curl https://api.kiteml.com/v1/keys/me \
  -H "Authorization: Bearer $KITE_API_KEY"

A valid key returns the key’s identity and scopes:

{
  "object": "api_key",
  "id": "key_01J8X4...",
  "name": "ci-augmentations",
  "scopes": ["augmentations:read", "augmentations:write"],
  "created_at": "2026-07-21T09:00:00Z"
}

An invalid or revoked key returns 401 Unauthorized.

Scopes

Scopes are resource:verb strings. write implies read for the same resource, so a key with augmentations:write can also read augmentations. Grant a key the narrowest scopes that its job needs. A CI task that only starts runs needs augmentations:write and nothing else, so a leaked key can’t read your usage or credit balance.

Scope	Grants
`augmentations:write`	Create and cancel augmentation runs (implies `:read`)
`augmentations:read`	List and read augmentations, episodes, and downloads
`training_runs:write`	Launch and cancel training runs (implies `:read`)
`training_runs:read`	List and read training runs, logs, and the policy and hardware catalogs
`usage:read`	Read token usage and credit balance

A call whose key is missing the required scope returns 403 with code missing_scope. Scope each key to the job it does. A CI pipeline that only launches training needs training_runs:write and nothing else — it can start and cancel runs, while a leaked key still can’t read your augmentations, your usage, or your credit balance.

Errors

Every error returns the same envelope. type maps to the HTTP status; code is a stable, specific reason you can branch on; request_id identifies the request — include it in any support message.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "episode_count must be between 1 and 50",
    "param": "config.episode_count",
    "request_id": "req_01J8X4..."
  }
}

Status	Common `code`	Meaning
`400`	`parameter_invalid`	Malformed or out-of-range field (named in `param`)
`401`	`unauthenticated`	Missing, invalid, or expired API key
`402`	`insufficient_tokens`	Not enough credits
`403`	`missing_scope`	The key lacks the scope this call requires
`404`	`resource_not_found`	No such resource
`409`	`idempotency_key_reused`	`Idempotency-Key` reused with a different payload
`429`	`rate_limit_exceeded`	Rate limited — honor the `Retry-After` header
`5xx`	`api_error`	Server error — safe to retry idempotent requests

Keep your key server-side. Never ship it in a browser, mobile app, or public repository. If a key leaks, revoke it from the dashboard immediately and create a scoped replacement.

​Create a key

​Authenticate a request

​Scopes

​Errors

Create a key

Authenticate a request

Scopes

Errors