Authentication and scopes | Kuudo API Documentation

API keys and access tokens

An API key is a long-lived sk_live_* or sk_test_* credential linked to a local M2M client. The prefix reflects that client’s production or development setting; it does not select a separate API server or provide a sandbox isolation guarantee.

Exchange your key at POST /api/auth/token-exchange, sending Authorization: Bearer <api_key>. No request body is required. This returns an access JWT, its lifetime, granted scopes, organization ID, and client ID.

Send that JWT as Authorization: Bearer <access_token> on protected integration routes. A raw API key cannot substitute for this JWT.

The default access-token lifetime is 900 seconds, with supported client settings from 300 to 900 seconds. Exchange requires an active, unexpired key and an active local M2M client. Organization routes revalidate the live API-key/client binding, so keep both active for subsequent calls.

POST /api/auth/exchange-api-key is a deprecated compatibility route. Its response omits organization_id and client_id; use the canonical route for new integrations.

Credential selection

Endpoint family	Credential
Token exchange	Raw API key in the Bearer header
Servers, environments, deployments, storage, skill download	Exchanged access JWT
Amazon identities and token vending	API-key-derived access JWT
Authorization invitations (development contract)	API-key-derived access JWT
npm registry metadata and tarballs	Raw API key in the Bearer header
Custom API-key introspection	Raw API key in the request body’s `token` field

The general scoped routes can also accept appropriately issued Better Auth OAuth access tokens. Amazon machine routes and authorization invitations reject those other OAuth bearer types. The API-key flow above is the starting point for M2M integrations; do not interchange API keys, M2M clients, and OAuth applications.

Required scopes

Every scope listed for an endpoint is required. For example, attaching or removing server storage requires both servers:write and storage:write.

Family	Read	Change	Delete
Servers	`servers:read`	`servers:write`	`servers:delete`
Provider environments	`environments:read`	`environments:write`	`environments:delete`
Deployment environments/jobs	`deployments:read`	`deployments:write`	—
Integration deployment	—	`deployments:write`	—
Storage	`storage:read`	`storage:write`	`storage:delete`
Skills/downloads/registry	`skills:read`	—	—
Amazon identities	`amazon-connections:read`	—	—
Amazon token vending	—	`amazon-tokens:vend`	—
Authorization invitations	`authorization-invitations:read`	`authorization-invitations:write`	`authorization-invitations:write`

Custom Docker validation additionally requires environments:read together with deployments:write. Server storage reads require servers:read and storage:read.

Organization and provider access

Organization context comes from the authenticated principal. Requesting another organization’s resource ID does not grant access to it. The invitation API permits an optional X-Organization-Id header as a consistency check; it must match the authenticated organization and cannot select another tenant.

Amazon access additionally depends on the M2M client’s authorization policy. Restricted clients need effective explicit or kind grants; a scope alone does not grant access to a provider account. Creating an invitation does not grant token access to its resulting authorization.

Introspection

Use POST /api/auth/introspect when your gateway needs to inspect a raw Kuudo API key. Supply JSON { "token": "<api_key>" } or a form-encoded token field. Invalid, missing, or expired keys return HTTP 200 with { "active": false }.

This custom endpoint does not introspect JWTs or Better Auth OAuth tokens. Active responses include org_id, client_id, scopes, and API-key context.