Identity & Access Management

Preview — pending review

This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.

Get an API token's detail and usage read model

GET
/scopes/{scopeId}/iam/api-tokens/{apiTokenId}

Retrieves the API token detail page read model for one API token: the token record (name, description, masked prefix, scopes, creator, created/expiry timestamps, last-used time and IP, CIDR allowlist, status) plus the usage panels — the recent call log (method, path, HTTP status, source IP, latency) and the 14-day call/error volume series. The full secret is never present in this response; only the non-sensitive prefix is shown. Validation: scopeId must be an accessible scope and apiTokenId must reference a token within it; unknown or out-of-scope ids map to NOT_FOUND (404). No mutation parameters exist. Async & state: Synchronous read; no state change. Errors: 401 when unauthenticated; 403 when the caller lacks IAM read permission on the scope; 404 when the token does not exist in this scope; 500 on read-model failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required. The response carries no ETag; rotate, revoke and delete do not check If-Match.

Authorization

bearerToken
headerAuthorizationBearer <token>

An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

apiTokenId*string

Identifier of the API token.

Response Body

API token detail read model including recent calls and usage series (secret omitted).

application/json
  1. response

Detail read model — token record plus usage panels.

id*string

Token identifier, e.g. "tok_a1b2".

name*string

Token name (lowercase letters, digits, hyphens), e.g. "ci-deploy-prod".

description*string

Free-text purpose description.

prefix*string

Non-sensitive secret prefix shown in the UI, e.g. "pc_live_7Qx9".

scopes*array<string>

Granted permission scopes, e.g. "compute:write", "billing:read".

createdBy*string

Display name of the user who created the token.

createdAt*string
Formatdate-time
expiresAt*|

Expiry timestamp, or null when the token never expires.

Formatdate-time
lastUsedAt*|

When the token last authenticated a call, or null if never used.

Formatdate-time
lastUsedIp*|

Source IP of the most recent call, or null if never used.

ipAllowlist*array<string>

CIDR allowlist; empty array = no restriction (any IP).

status*ApiTokenStatus

Lifecycle status of an API token.

Value in"ACTIVE""EXPIRED""REVOKED"
recentCalls*array<>

Recent call log, newest first.

usageSeries*array<>

14-day call/error volume series.

curl -X GET "https://example.com/scopes/string/iam/api-tokens/string"
{  "id": "string",  "name": "string",  "description": "string",  "prefix": "string",  "scopes": [    "string"  ],  "createdBy": "string",  "createdAt": "2019-08-24T14:15:22Z",  "expiresAt": "2019-08-24T14:15:22Z",  "lastUsedAt": "2019-08-24T14:15:22Z",  "lastUsedIp": "string",  "ipAllowlist": [    "string"  ],  "status": "ACTIVE",  "recentCalls": [    {      "id": "string",      "at": "2019-08-24T14:15:22Z",      "method": "GET",      "path": "string",      "status": 0,      "ip": "string",      "latencyMs": 0    }  ],  "usageSeries": [    {      "label": "string",      "calls": 0,      "errors": 0    }  ]}