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.

List and query API tokens

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

Lists API tokens in the active scope for the API tokens page table: name, description, masked prefix (e.g. pc_live_7Qx9), granted scopes, creator, created/expiry timestamps, last-used time and IP, the CIDR allowlist, and lifecycle status. The full secret is NEVER returned by this endpoint — it is revealed exactly once at create/rotate time. This single endpoint also serves the iam.api_token.search_filter_sort action: q matches token name and prefix; the status filter mirrors the UI's Total/Active/Expired/Revoked chips. Validation: scopeId must be an accessible scope (NOT_FOUND semantics fold into 403/404 at the scope layer); status must be one of ACTIVE|EXPIRED|REVOKED; pagination/sort parameters must be within documented ranges — violations map to VALIDATION_FAILED (422). Async & state: Synchronous read; no state change. Errors: 401 when unauthenticated; 403 when the caller lacks IAM read permission on the scope; 422 on malformed filter/pagination parameters; 500 on read-model failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required.

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.

Query Parameters

region?string

Restrict the result set to a single region.

Match^[a-z][a-z0-9-]{1,39}$
q?string

Free-text search.

sort?string

Field to sort by (entity-specific; defaults to the entity's natural order).

order?string

Sort direction.

Default"asc"
Value in"asc""desc"
page?integer

1-based page number.

Range1 <= value
Default1
pageSize?integer

Items per page (max 200).

Range1 <= value <= 200
Default50
status?string

Filter by token lifecycle status (UI chips Total / Active / Expired / Revoked).

Value in"ACTIVE""EXPIRED""REVOKED"

Response Body

Paginated collection of API tokens in the active scope (secrets omitted).

application/json
  1. response
data*array<>
meta*

Pagination envelope metadata. List responses are always { data, meta } — never a naked array.

curl -X GET "https://example.com/scopes/string/iam/api-tokens"
{  "data": [    {      "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"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}