> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kuudo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kuudo.com/_mcp/server.

# Authentication and scopes

> Choose the correct credential and bind requests to your organization.

## 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, client ID, and the
organization's current plan.

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.

## Credential selection

| Endpoint family                                  | Credential                                      |
| ------------------------------------------------ | ----------------------------------------------- |
| Token exchange                                   | Raw API key in the Bearer header                |
| Servers, environments, deployments, storage      | Exchanged access JWT                            |
| Amazon identities and token vending              | API-key-derived access JWT                      |
| Authorization invitations (development contract) | API-key-derived access JWT                      |
| 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.

## Delegated Agent Auth

For Claude Code, Cursor, Codex, and other Agent Auth clients, follow the
[AI-agents guide](/guides/ai-agents) and the
[Agent Auth API reference](/api-reference/agent-auth/discover-agent-auth).
The SDK uses host-signed and agent-signed protocol JWTs, with human approval
for `read_account` and `read_organization`. Those capabilities are separate
from the REST scopes below; Agent Auth does not call token exchange.

## 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`                  |
| 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.