Rotate a secret (sync or async)
const url = 'https://example.com/v1/secrets/example/rotate?scopeKind=tenant';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"scope":{"kind":"tenant","tenantId":"example"},"envName":"example","newValue":"example","revokeOldAfterMs":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://example.com/v1/secrets/example/rotate?scopeKind=tenant' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "scope": { "kind": "tenant", "tenantId": "example" }, "envName": "example", "newValue": "example", "revokeOldAfterMs": 1 }'Requires the secrets:rotate capability. The scope comes from body scope, else from scopeKind + scopeId in the query; one of them is required, and when both are present they must name the same scope. Authorization checks that scope. Sync providers return 201 with { kind: "sync", newVersionId, oldVersionId, oldVersionRevokedAt? }. Async providers return 202 with { kind: "async", rotationId, statusUrl, eventsUrl }; poll via GET /v1/secrets/:name/rotations/:rotationId or subscribe via SSE at the events URL. kind is the discriminant.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Secret name (opaque string within the tenant + envName).
Query Parameters
Section titled “Query Parameters”Per-environment slug. [a-z][a-z0-9-]{0,62} — RFC-1035-like label.
Alternative to body envName. When both are present they must match (400 env-name-mismatch).
Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.
Alternative to body scope (with scopeId). When both are present they must name the same scope (400 scope-mismatch).
Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.
Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).
Request Body
Section titled “Request Body”object
Per-environment slug. [a-z][a-z0-9-]{0,62} — RFC-1035-like label.
Responses
Section titled “Responses”Sync rotation complete.
object
Example
{ "kind": "sync"}Async rotation accepted; poll or subscribe.
object
Example
{ "kind": "async"}A body that fails validation (bad-input), or a rotation the store refuses as it would the write: secret-value-too-large for a new value over its size limit, or reserved-name-prefix for a kindgi. name.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Bearer token missing secrets:rotate capability.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Unknown secret.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Idempotency-Key was reused with a different body, or resource-state conflict. Or env-not-served: this runtime keeps every value under the env it serves (whoami’s servedEnv, with refusesOtherEnvs), so a value under another env would never be read. details.envName is the env asked for, details.servedEnv the one to use. A secret that a provider, MCP endpoint or webhook endpoint registered before names under that env, at the scope it’s read at, is still written: it’s read there. Nothing is stored otherwise.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The request body is over the API’s limit (request-too-large; details.maxBytes says how much).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}secret-provider-rate-limited: the secrets store’s external provider is limiting the runtime’s requests.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Server error (unmapped domain code or framework crash).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The store doesn’t rotate (secret-operation-unsupported): under kindgi dev secrets live in the env files and have no versions; the message says what to do instead.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}secret-provider-unauthorized: the secrets store’s external provider refused the runtime’s credentials.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}secret-provider-unavailable: the secrets store’s external provider can’t be reached.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}See also
GET /v1/secrets/{name}: Get secret metadataDELETE /v1/secrets/{name}: Revoke a secretGET /v1/secrets/{name}/versions: List secret versionsGET /v1/secrets/{name}/versions/{versionId}: Get one secret-version record- Error code
bad-input - Error code
env-not-served - Error code
request-too-large - Error code
reserved-name-prefix - Error code
secret-operation-unsupported - Error code
secret-provider-rate-limited - Error code
secret-provider-unauthorized - Error code
secret-provider-unavailable - Error code
secret-value-too-large - Every error code