> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/admin-api/authentication.md).

# Authentication

Get an admin token through the device flow or the OAuth authorization-code grant, and give it up again.

## Begin an authorization-code grant with S256 PKCE

> Starts an OAuth authorization-code grant with S256 PKCE for a client identified by its client ID metadata document.\
> \
> \- Validates the client and the exact registered redirect before any redirect; untrusted clients receive a local error page.\
> \- Consent is completed through the authenticated dashboard bridge.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"authentication","summary":"Authentication","description":"Get an admin token through the device flow or the OAuth authorization-code grant, and give it up again."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[],"paths":{"/auth/authorize":{"get":{"operationId":"authorizeOAuth","tags":["authentication"],"summary":"Begin an authorization-code grant with S256 PKCE","description":"Starts an OAuth authorization-code grant with S256 PKCE for a client identified by its client ID metadata document.\n\n- Validates the client and the exact registered redirect before any redirect; untrusted clients receive a local error page.\n- Consent is completed through the authenticated dashboard bridge.","parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string"},"description":"HTTPS client ID metadata document URL."},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string"},"description":"Registered redirect URI."},{"name":"response_type","in":"query","required":true,"schema":{"type":"string","enum":["code"]},"description":"Authorization code response."},{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string"},"description":"Base64url SHA-256 of the verifier."},{"name":"code_challenge_method","in":"query","required":true,"schema":{"type":"string","enum":["S256"]},"description":"Required PKCE method."},{"name":"resource","in":"query","required":true,"style":"form","explode":true,"schema":{"type":"array","minItems":1,"items":{"type":"string"}},"description":"https://access.tryterra.co/api/v3/admin/mcp"},{"name":"scope","in":"query","schema":{"type":"string"},"description":"Space-separated admin scopes. An empty scope selects the MCP preset."},{"name":"state","in":"query","schema":{"type":"string"},"description":"Opaque state echoed unchanged."},{"name":"requested_dev_ids","in":"query","schema":{"type":"string"},"description":"Optional space-separated environment IDs."}],"responses":{"302":{"description":"Dashboard consent redirect, or a client error redirect with state and iss.","headers":{"Location":{"description":"Redirect destination.","schema":{"type":"string"}}}},"400":{"description":"Client or redirect is untrusted; no redirect is issued.","content":{"text/html":{"schema":{"type":"string"}}}},"503":{"description":"Authorization-code flow is disabled (temporarily_unavailable JSON), or the client's metadata could not be fetched (an HTML page with Retry-After; no redirect is issued because the redirect URI is unverified).","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}},"text/html":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"OAuthError":{"type":"object","description":"RFC 6749 §5.2 error envelope, returned to form-encoded (RFC 8628 wire mode) requests.","properties":{"error":{"type":"string","enum":["invalid_request","invalid_scope","invalid_grant","unsupported_grant_type","authorization_pending","slow_down","access_denied","expired_token","server_error","invalid_client","temporarily_unavailable","invalid_client_metadata","invalid_redirect_uri"]},"error_description":{"type":"string"}},"required":["error"]}}}}
```

## Begin device-pairing auth (RFC 8628)

> Starts device pairing with a standard RFC 8628 §3.1 device authorization request.\
> \
> \- Speaks only the OAuth wire format: a form-encoded body and a JSON \`200\` response with \`Cache-Control: no-store\`.\
> \- Errors use the RFC 6749 §5.2 error envelope.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"authentication","summary":"Authentication","description":"Get an admin token through the device flow or the OAuth authorization-code grant, and give it up again."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[],"paths":{"/auth/device":{"post":{"operationId":"startDeviceAuth","tags":["authentication"],"responses":{"200":{"description":"Device pairing started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceStartResponse"}}}},"400":{"description":"invalid_request | invalid_scope (RFC 6749 §5.2 envelope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}},"summary":"Begin device-pairing auth (RFC 8628)","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/DeviceStartFormRequest"}}}},"description":"Starts device pairing with a standard RFC 8628 §3.1 device authorization request.\n\n- Speaks only the OAuth wire format: a form-encoded body and a JSON `200` response with `Cache-Control: no-store`.\n- Errors use the RFC 6749 §5.2 error envelope."}}},"components":{"schemas":{"DeviceStartResponse":{"type":"object","description":"RFC 8628 §3.2 device authorization response. The four fields the RFC requires are required here; a client that cannot read device_code has no way to poll.","properties":{"device_code":{"type":"string"},"user_code":{"type":"string"},"verification_uri":{"type":"string"},"expires_in":{"type":"integer"},"verification_uri_complete":{"type":"string"},"interval":{"type":"integer","description":"Polling interval in seconds. RFC 8628 §3.2: absent means 5."}},"required":["device_code","user_code","verification_uri","expires_in"]},"OAuthError":{"type":"object","description":"RFC 6749 §5.2 error envelope, returned to form-encoded (RFC 8628 wire mode) requests.","properties":{"error":{"type":"string","enum":["invalid_request","invalid_scope","invalid_grant","unsupported_grant_type","authorization_pending","slow_down","access_denied","expired_token","server_error","invalid_client","temporarily_unavailable","invalid_client_metadata","invalid_redirect_uri"]},"error_description":{"type":"string"}},"required":["error"]},"DeviceStartFormRequest":{"type":"object","description":"RFC 8628 §3.1 device authorization request (form-encoded wire mode).","properties":{"client_id":{"type":"string","description":"Public client identifier; recorded as the pairing session's client name."},"scope":{"type":"string","description":"Space-separated scopes; omitted = the default grantable set. The device flow issues an admin token, so the grantable names are the ones the adminToken scope registry marks `admin` or `both` in x-scope-planes. Data-plane names are rejected with 400 invalid_scope."},"requested_dev_ids":{"type":"string","description":"Optional space-separated audience dev-ids (Terra extension parameter). Omitted = the whole account. Account-level scopes cannot be combined with an audience."},"requester_hostname":{"type":"string","description":"The requesting machine's hostname, shown on the approval page. Display-only and unverified; the user code remains the check."}},"required":["client_id"]}}}}
```

## Exchange an authorization code or poll a device grant

> Exchanges an authorization code for a token, or polls a device grant, speaking only the OAuth wire format.\
> \
> \- \`authorization\_code\` takes \`code\`, an S256 \`code\_verifier\`, the canonical MCP resource and an optional exact \`redirect\_uri\`.\
> \- The client authenticates by its declared method: \`none\` with a CIMD \`client\_id\`, or \`private\_key\_jwt\` for CIMD clients that declare it, in which case \`client\_id\` may be omitted.\
> \- The device grant is the RFC 8628 §3.4 request with \`grant\_type\` \`urn:ietf:params:oauth:grant-type:device\_code\`.\
> \- Form-encoded body; RFC 6749 §5.1 token response, §5.2/§3.5 error envelope, \`Cache-Control: no-store\`.\
> \- No refresh tokens are issued; rotate with \`POST /tokens/self/rotate\`.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"authentication","summary":"Authentication","description":"Get an admin token through the device flow or the OAuth authorization-code grant, and give it up again."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[],"paths":{"/auth/token":{"post":{"operationId":"pollToken","tags":["authentication"],"responses":{"200":{"description":"Token minted (RFC 6749 §5.1).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthTokenResponse"}}}},"400":{"description":"authorization_pending | slow_down | access_denied | expired_token | invalid_request | unsupported_grant_type | invalid_grant | invalid_client (RFC 8628 §3.5 / RFC 6749 §5.2 envelope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"401":{"description":"Header client authentication failed (RFC 6749 §5.2).","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"503":{"description":"temporarily_unavailable with Retry-After when the authorization-code flow is disabled, client metadata or keys cannot be fetched, or assertion replay protection is unavailable.","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}},"summary":"Exchange an authorization code or poll a device grant","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TokenPollFormRequest"},{"$ref":"#/components/schemas/AuthorizationCodeFormRequest"},{"$ref":"#/components/schemas/AuthorizationCodeAssertionFormRequest"}]}}}},"description":"Exchanges an authorization code for a token, or polls a device grant, speaking only the OAuth wire format.\n\n- `authorization_code` takes `code`, an S256 `code_verifier`, the canonical MCP resource and an optional exact `redirect_uri`.\n- The client authenticates by its declared method: `none` with a CIMD `client_id`, or `private_key_jwt` for CIMD clients that declare it, in which case `client_id` may be omitted.\n- The device grant is the RFC 8628 §3.4 request with `grant_type` `urn:ietf:params:oauth:grant-type:device_code`.\n- Form-encoded body; RFC 6749 §5.1 token response, §5.2/§3.5 error envelope, `Cache-Control: no-store`.\n- No refresh tokens are issued; rotate with `POST /tokens/self/rotate`."}}},"components":{"schemas":{"OAuthTokenResponse":{"type":"object","description":"RFC 6749 §5.1 token response, returned to form-encoded (RFC 8628 wire mode) polls. No refresh tokens are issued — rotate via POST /tokens/self/rotate instead.","properties":{"access_token":{"type":"string","description":"The minted bearer, returned once by the token endpoint."},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Seconds until the access token expires. Omitted when the token never expires."},"scope":{"type":"string","description":"Space-separated granted scopes."},"token_id":{"type":"string","format":"uuid"}},"required":["access_token","token_type","scope","token_id"]},"OAuthError":{"type":"object","description":"RFC 6749 §5.2 error envelope, returned to form-encoded (RFC 8628 wire mode) requests.","properties":{"error":{"type":"string","enum":["invalid_request","invalid_scope","invalid_grant","unsupported_grant_type","authorization_pending","slow_down","access_denied","expired_token","server_error","invalid_client","temporarily_unavailable","invalid_client_metadata","invalid_redirect_uri"]},"error_description":{"type":"string"}},"required":["error"]},"TokenPollFormRequest":{"type":"object","description":"RFC 8628 §3.4 device access token request (form-encoded wire mode).","properties":{"grant_type":{"type":"string","enum":["urn:ietf:params:oauth:grant-type:device_code"]},"device_code":{"type":"string"},"client_id":{"type":"string","description":"Must match the client_id the device_code was issued to; a mismatch is invalid_grant."}},"required":["grant_type","device_code","client_id"]},"AuthorizationCodeFormRequest":{"type":"object","description":"Authorization-code exchange with mandatory S256 PKCE, authenticated as a public client by client_id alone.","properties":{"grant_type":{"type":"string","enum":["authorization_code"]},"code":{"type":"string"},"redirect_uri":{"type":"string"},"code_verifier":{"type":"string"},"resource":{"type":"string","enum":["https://access.tryterra.co/api/v3/admin/mcp"]},"client_id":{"type":"string","description":"The client ID metadata document URL."},"client_assertion_type":{"description":"Not sent by public clients; a private_key_jwt client sends both assertion fields and matches the assertion variant.","not":{}},"client_assertion":{"description":"Not sent by public clients; a private_key_jwt client sends both assertion fields and matches the assertion variant.","not":{}}},"required":["grant_type","code","code_verifier","resource","client_id"]},"AuthorizationCodeAssertionFormRequest":{"type":"object","description":"Authorization-code exchange with mandatory S256 PKCE, authenticated by a private_key_jwt assertion whose sub names the client.","properties":{"grant_type":{"type":"string","enum":["authorization_code"]},"code":{"type":"string"},"redirect_uri":{"type":"string"},"code_verifier":{"type":"string"},"resource":{"type":"string","enum":["https://access.tryterra.co/api/v3/admin/mcp"]},"client_id":{"type":"string","description":"Optional with an assertion; when present it must equal the assertion's iss and sub."},"client_assertion_type":{"type":"string","enum":["urn:ietf:params:oauth:client-assertion-type:jwt-bearer"]},"client_assertion":{"type":"string","description":"An asymmetrically signed JWT of at most 4096 bytes with iss and sub equal to client_id, a single-valued aud equal to the issuer https://access.tryterra.co or the token endpoint https://access.tryterra.co/api/v3/admin/auth/token, a single-use jti and an exp at most five minutes ahead."}},"required":["grant_type","code","code_verifier","resource","client_assertion_type","client_assertion"]}}}}
```

## List the scopes a token can be granted

> Returns the scope registry this deployment grants from, with the same vocabulary, planes, risk lists and presets \`securitySchemes.adminToken\` carries, so a client or approval page can show and request scopes without pinning a copy of this document.\
> \
> \- Needs no token.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"authentication","summary":"Authentication","description":"Get an admin token through the device flow or the OAuth authorization-code grant, and give it up again."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[],"paths":{"/auth/scopes":{"get":{"operationId":"getScopeRegistry","tags":["authentication"],"summary":"List the scopes a token can be granted","description":"Returns the scope registry this deployment grants from, with the same vocabulary, planes, risk lists and presets `securitySchemes.adminToken` carries, so a client or approval page can show and request scopes without pinning a copy of this document.\n\n- Needs no token.","responses":{"200":{"description":"The scope registry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeRegistry"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"schemas":{"ScopeRegistry":{"type":"object","description":"The adminToken scope registry this deployment grants from: the same vocabulary and lists securitySchemes.adminToken publishes, served live so a client can read them without pinning a copy of the spec.","properties":{"scopes":{"type":"object","description":"Every scope on both planes, keyed by name, each with the sentence an approval page shows the person granting it.","additionalProperties":{"type":"string"}},"planes":{"type":"object","description":"Which token kinds may hold each scope, as in x-scope-planes. POST /auth/device grants only `admin` and `both`.","additionalProperties":{"type":"string","enum":["admin","data","both"]}},"dangerous":{"type":"object","description":"Each dangerous scope and what it puts at stake, as in x-scope-dangerous. A default grant leaves these off.","additionalProperties":{"type":"string","enum":["money","access","team"]}},"sensitive":{"type":"array","description":"Scopes that disclose what the approver already sees in the dashboard, as in x-scope-sensitive. Granted by default, labeled.","items":{"type":"string"}},"account_level":{"type":"array","description":"Scopes that act on the whole account, as in x-scope-account-level. A token limited to environments cannot hold them.","items":{"type":"string"}},"presets":{"type":"array","description":"The named grant sets, in the order the approval page offers them. The first is the default.","items":{"$ref":"#/components/schemas/ScopePreset"}}},"required":["scopes","planes","dangerous","sensitive","account_level","presets"]},"ScopePreset":{"type":"object","description":"A named grant set the approval page offers, from x-scope-presets.","properties":{"name":{"type":"string"},"summary":{"type":"string","description":"What the preset is for, as the approval page shows it."},"mcp_name":{"type":"string","description":"The label an MCP client's approval page shows instead of name; present on exactly one preset."},"mcp_summary":{"type":"string","description":"The summary shown beside mcp_name."},"scopes":{"type":"array","items":{"type":"string"}}},"required":["name","summary","scopes"]},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}}}}
```
