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.

Revoke a key immediately

POST
/scopes/{scopeId}/iam/service-accounts/{serviceAccountId}/keys/{keyId}/actions/revoke

Revokes the selected key (UI "Revoke" in the Keys tab). Revocation is immediate and irreversible: the key's status becomes revoked, clients still presenting it fail authentication, and per the key-hygiene panel any tokens already issued with it expire within one hour. The UI toast warns "Key … revoked — clients using it will fail". A revoked key remains listed for audit purposes but exposes no further actions. Validation: the service account and key must exist and be visible in the scope (else 404 NOT_FOUND); the key's current state must permit revoke — a key already revoked is rejected → 409 CONFLICT; caller must hold a key-management role (owner|admin) else 403 FORBIDDEN. Async & state: Synchronous command — 200 with the key in its terminal revoked state. The key's private-key secret is purged from the secret store so it can never authenticate again; the revoked key stays listed for audit and the account's keyCount/oldestKeyAgeDays counters update immediately. Errors: 401 unauthenticated; 403 lacks key-management permission; 404 unknown account or key; 409 CONFLICT when the key is already revoked; 500 revocation failure. Idempotency/Concurrency: Idempotency-Key is optional; when sent it is reserved atomically (single-winner) — replaying the same key returns the original 200 result rather than a 409, making UI retries safe.

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.

serviceAccountId*string

Service account identifier.

keyId*string

Key identifier.

Header Parameters

Idempotency-Key?string

Optional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.

Formatuuid

Response Body

Key revoked; returns the key in its terminal revoked state.

application/json
  1. response

Long-lived key metadata. Private key material is never present here — it is revealed exactly once at creation.

id*string
fingerprint*string

40-hex-character public fingerprint (also the private_key_id in the one-time credential).

createdAt*string
Formatdate-time
lastUsedAt*|

Last authentication with this key; null when never used.

Formatdate-time
expiresAt*string

Hard expiry at the 365-day maximum lifetime.

Formatdate-time
status*string

expiring = 30 days or less remaining before expiry.

Value in"active""expiring""expired""revoked"
ageDays*integer

Key age in days; above 90 it is flagged stale per the rotation guideline.

scopes*array<>

The action scopes the key acts within, sorted; never iam:write. A key minted before scopes existed was given the whole key catalogue (catalogue minus iam:write).

curl -X POST "https://example.com/scopes/string/iam/service-accounts/string/keys/string/actions/revoke"
{  "id": "string",  "fingerprint": "string",  "createdAt": "2019-08-24T14:15:22Z",  "lastUsedAt": "2019-08-24T14:15:22Z",  "expiresAt": "2019-08-24T14:15:22Z",  "status": "active",  "ageDays": 0,  "scopes": [    "compute:read"  ]}