Authentication
API keys, OAuth sign-in, roles and scopes, and what agents may do.
Every request under /v1 carries one credential as a bearer token, and acts in one organization:
Authorization: Bearer <credential>
Api-Version: 2026-10-15The credential is either an API key (cc_…) or a person's OAuth access token.
API keys
Create and revoke keys in the console under Settings > API keys. A key has a name, a kind, a set of permissions (scopes) and an expiry, and its secret is shown once, when you create it.
| Kind | For | Rules |
|---|---|---|
| Standard | Programs, scripts, CI, autoscalers | Expires only if you give it a lifetime |
| Agent | AI agents that run without a person | Expires within 90 days (30 by default); stops working when the person who made it leaves the organization; can carry limits of its own; the only kind the MCP server accepts |
A key can carry only the instance, reservation and alert permissions of the person who made it. Everyone sees the keys they made; owners see and can revoke every key in the organization.
| Permission in the console | Scope | Lets the key |
|---|---|---|
| View instances | instances:read | List and get instances, and read their metrics |
| Create and extend instances | instances:write | Create, rename and extend instances, open ports, add dedicated IPv4, register domains |
| Delete instances | instances:delete | Delete instances |
| View reservations | reservations:read | Find offerings, list and get reservations |
| Request and withdraw reservations | reservations:write | Request and withdraw GPU reservations |
| View alerts and notifications | alerts:read | List alert channels, subscriptions and notifications |
| Change alert channels and subscriptions | alerts:write | Create, test and delete channels and subscriptions, and rotate a webhook's signing secret |
The catalog (/v1/images, /v1/sizes, /v1/locations) and /v1/limits need a valid credential and no scope.
OAuth
People and the apps they sign in to use OAuth 2.1 with PKCE, or the device flow on a machine without a browser. The authorization server is https://auth.confidential.ai; GET https://api.cloud.confidential.ai/.well-known/oauth-protected-resource names it:
{
"resource": "https://api.cloud.confidential.ai",
"authorization_servers": ["https://auth.confidential.ai"],
"bearer_methods_supported": ["header"]
}Ask for a token for the resource https://api.cloud.confidential.ai (RFC 8707). The API refuses a token issued for any other resource, its own MCP server included. A token acts for one person, in the organization they choose when they sign in, with the scopes of their role there, so clients ask for no API scopes.
| Role | Scopes |
|---|---|
viewer | instances:read, reservations:read, alerts:read |
member | A viewer's, and instances:write, instances:delete, reservations:write |
owner | A member's, and alerts:write to manage alerts, and approving GPU reservations and inviting people in the console |
Managing the organization, its invitations and API keys, and approving reservations, need a person signed in to the console; no key and no other app can do them.
Agents
An agent key, and a token issued to any app but the console, act as an agent:
- It is held to the limits set for it, which
GET /v1/limitsreturns with what is in use. - A GPU reservation it requests waits for an owner's approval in the console.
- It never manages keys or people and never approves anything.
See Connect an AI agent.
When a credential is refused
| Response | Means | Do |
|---|---|---|
401 unauthenticated | The credential is missing, malformed, unknown or revoked, or the access token expired | Refresh the token or sign in again; check the key |
401 key_expired | The API key expired | Create a new key |
403 insufficient_scope | The credential lacks a scope; details.requiredScopes lists every scope the operation needs | Use a key with those permissions |
Every 401 carries WWW-Authenticate with resource_metadata, the address of the protected resource metadata, so OAuth clients can find where to sign in.