Emergency revoke a credential version

Blocks every later use of this version immediately, including by live published agents, without publication or a draft edit. Every later tool call that would use the revoked version is refused, including later tool calls inside a call that is already running (its MCP session is closed); an external action already performed is not undone. Refused tool calls appear as failed tool outcomes with credential_unavailable; the call itself continues. Irreversible: rotate, rebind and publish to recover. New draft references and publications that pin a revoked version refuse with credential_unavailable. Rollback never re-enables a revoked version. Revoking an already revoked version returns its current state. Use GET /secrets/{secret_id}/references to find affected agents.

Authentication

AuthorizationBearer

Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.

Path parameters

secret_idstringRequired1-128 characters

Resource identity within the authenticated workspace.

versionintegerRequired>=1

Secret version number.

Headers

Idempotency-KeystringRequired1-255 characters

Stable key per logical intent, 1–255 printable characters. Persist it before sending. Retry the same key/body after an uncertain result for 24 hours. A changed body conflicts. Beyond retention, reconcile the resource before retrying; this is not permanent deduplication. Current authorization is rechecked on replay. Evaluation order: authenticate and check current authorization; look up intent; replay its stored receipt before checking the current revision; only a new intent evaluates If-Match and executes. Fingerprint includes method, path, body and original If-Match. A changed request returns idempotency_key_reused. The server stores only a keyed (HMAC) fingerprint, and no error or response ever returns a fingerprint or hash of a request. In-flight intent returns 409 idempotency_in_progress with Retry-After; retry the same intent after reconciliation. Receipts describe that attempt, not current resource state. A replay returns the original status code and body, with the response header Idempotent-Replayed: true.

Request

This endpoint expects an object.

reasonenumRequired

Allowed values:

Response headers

X-Request-IdstringOptional

Safe server request correlation ID.

RateLimit-LimitintegerOptional

Requests allowed in the current window for the tightest applicable limit.

RateLimit-RemainingintegerOptional

Requests left in the current window.

RateLimit-ResetintegerOptional

Seconds until the current window resets.

Idempotent-ReplayedstringOptional

true when this response replays a stored Idempotency-Key result. The status and body equal the original.

Response

Emergency revoke a credential version.

secret_idstring<=128 characters

Opaque sec identifier. Do not parse its contents.

versioninteger>=1

statestring

Open response vocabulary. Preserve unknown values; never assume they mean success.

created_atdatetime

revoked_atdatetime or null

revoke_reasonstring or null

Reason given to revokeSecretVersion. Open response vocabulary. Preserve unknown values; never assume they mean success.

usageobject

Reference counts at response time. Use GET /secrets/{secret_id}/references for the exact consumers.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

413

Content Too Large Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error