# Rotate a secret (sync or async) POST /v1/secrets/{name}/rotate ```sh curl --request POST \ --url 'https://example.com/v1/secrets/example/rotate?scopeKind=tenant' \ --header 'Authorization: Bearer ' \ --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 - **[bearerAuth](https://docs.kindgi.com/v0.1.10/reference/api.md#bearerauth)** ## Parameters ### Path Parameters **name** required string \>= 1 characters Secret name (opaque string within the tenant + envName). ### Query Parameters **envName** Per-environment slug. `[a-z][a-z0-9-]{0,62}` — RFC-1035-like label. string /^\[a-z]\[a-z0-9-]{0,62}$/ Alternative to body `envName`. When both are present they must match (400 `env-name-mismatch`). **scopeKind** Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId. string Allowed values: tenant org project Alternative to body `scope` (with `scopeId`). When both are present they must name the same scope (400 `scope-mismatch`). **scopeId** string \>= 1 characters 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 **Idempotency-Key** string \>= 1 characters 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 application/json object **scope** One of: - **object** object **kind** required string Allowed values: tenant **tenantId** required string - **object** object **kind** required string Allowed values: org **tenantId** required string **orgId** required string - **object** object **kind** required string Allowed values: project **tenantId** required string **projectId** required string **envName** Per-environment slug. `[a-z][a-z0-9-]{0,62}` — RFC-1035-like label. string /^\[a-z]\[a-z0-9-]{0,62}$/ **newValue** string **revokeOldAfterMs** integer ## Responses ### 201 Sync rotation complete. application/json object **kind** required string Allowed values: sync **newVersionId** required integer \>= 1 **oldVersionId** required integer \>= 1 **oldVersionRevokedAt** string format: date-time ##### Example ```json { "kind": "sync" } ``` ### 202 Async rotation accepted; poll or subscribe. application/json object **kind** required string Allowed values: async **rotationId** required string format: uuid **statusUrl** required string **eventsUrl** required string ##### Example ```json { "kind": "async" } ``` ### 400 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. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 401 Missing / malformed / expired / revoked bearer token. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 403 Bearer token missing `secrets:rotate` capability. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 404 Unknown secret. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 409 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. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 413 The request body is over the API’s limit (`request-too-large`; `details.maxBytes` says how much). application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 429 `secret-provider-rate-limited`: the secrets store’s external provider is limiting the runtime’s requests. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 500 Server error (unmapped domain code or framework crash). application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 501 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. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 502 `secret-provider-unauthorized`: the secrets store’s external provider refused the runtime’s credentials. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 503 `secret-provider-unavailable`: the secrets store’s external provider can’t be reached. application/json object **error** required object **code** required Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3). string **message** required string **details** Optional, kind-specific. object **_key_** additional properties any **requestId** required Server-assigned request id; also echoed via `X-Request-Id` header. string ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ## See also - [`GET /v1/secrets/{name}`: Get secret metadata](https://docs.kindgi.com/v0.1.10/reference/api/operations/secretsget.md) - [`DELETE /v1/secrets/{name}`: Revoke a secret](https://docs.kindgi.com/v0.1.10/reference/api/operations/secretsrevoke.md) - [`GET /v1/secrets/{name}/versions`: List secret versions](https://docs.kindgi.com/v0.1.10/reference/api/operations/secretslistversions.md) - [`GET /v1/secrets/{name}/versions/{versionId}`: Get one secret-version record](https://docs.kindgi.com/v0.1.10/reference/api/operations/secretsgetversion.md) - [Error code `bad-input`](https://docs.kindgi.com/v0.1.10/reference/errors.md#bad-input) - [Error code `env-not-served`](https://docs.kindgi.com/v0.1.10/reference/errors.md#env-not-served) - [Error code `request-too-large`](https://docs.kindgi.com/v0.1.10/reference/errors.md#request-too-large) - [Error code `reserved-name-prefix`](https://docs.kindgi.com/v0.1.10/reference/errors.md#reserved-name-prefix) - [Error code `secret-operation-unsupported`](https://docs.kindgi.com/v0.1.10/reference/errors.md#secret-operation-unsupported) - [Error code `secret-provider-rate-limited`](https://docs.kindgi.com/v0.1.10/reference/errors.md#secret-provider-rate-limited) - [Error code `secret-provider-unauthorized`](https://docs.kindgi.com/v0.1.10/reference/errors.md#secret-provider-unauthorized) - [Error code `secret-provider-unavailable`](https://docs.kindgi.com/v0.1.10/reference/errors.md#secret-provider-unavailable) - [Error code `secret-value-too-large`](https://docs.kindgi.com/v0.1.10/reference/errors.md#secret-value-too-large) - [Every error code](https://docs.kindgi.com/v0.1.10/reference/errors.md)