Skip to navigation
API referenceSecrets

Rotate a tool credential

Rotation creates a new immutable version with new write-only material. It does not switch any consumer: every tool, MCP server and published agent keeps its pinned version. To adopt the new version, replace each referencing tool or MCP server with {secret_id, version}, review the draft diff and publish each affected agent; calls admitted before that keep their version. Older versions stay active until you revoke them, so a cutover can proceed agent by agent.

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.

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.
valuestringRequiredformat: "password"1-8192 characters

Write-only credential material. Sealed inside the request transaction. Never returned, logged, included in diffs, errors, events or call evidence.

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

Rotate a tool credential.
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