Docs

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-15

The 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.

KindForRules
StandardPrograms, scripts, CI, autoscalersExpires only if you give it a lifetime
AgentAI agents that run without a personExpires 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 consoleScopeLets the key
View instancesinstances:readList and get instances, and read their metrics
Create and extend instancesinstances:writeCreate, rename and extend instances, open ports, add dedicated IPv4, register domains
Delete instancesinstances:deleteDelete instances
View reservationsreservations:readFind offerings, list and get reservations
Request and withdraw reservationsreservations:writeRequest and withdraw GPU reservations
View alerts and notificationsalerts:readList alert channels, subscriptions and notifications
Change alert channels and subscriptionsalerts:writeCreate, 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.

RoleScopes
viewerinstances:read, reservations:read, alerts:read
memberA viewer's, and instances:write, instances:delete, reservations:write
ownerA 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/limits returns 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

ResponseMeansDo
401 unauthenticatedThe credential is missing, malformed, unknown or revoked, or the access token expiredRefresh the token or sign in again; check the key
401 key_expiredThe API key expiredCreate a new key
403 insufficient_scopeThe credential lacks a scope; details.requiredScopes lists every scope the operation needsUse 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.

On this page