Atomically replace a key while preserving its grants and expiry
Generated from the checked-in source. Do not edit this reference by hand.
POST /api/v1/organizations/{organization}/projects/{project}/keys/{key}/rotate
Requires workspace write access. Workspace API keys do not authorize these management operations. Revokes the old secret atomically. The replacement preserves grants, expiry, spending identity and configured key policies; rotation does not reset consumed allowance.
Operation: rotateKey.
Authentication
Section titled “Authentication”Use the credential and permission scope described above. Each object below is an alternative; schemes within one object are required together.
[ { "bearerAuth": [] }]HTTP request
Section titled “HTTP request”Set NIU_ORIGIN to your installation origin (without /v1). Replace path, query and header placeholders with the required values. Query examples use curl 7.87 or newer to encode values with --url-query. Use the credential scope described above; a bearer token must have the authority required by this operation.
curl --fail-with-body -X POST "$NIU_ORIGIN/api/v1/organizations/{organization}/projects/{project}/keys/{key}/rotate" \ -H "Authorization: Bearer $NIU_BEARER_TOKEN"Parameters
Section titled “Parameters”organization
Section titled “organization”Location: path. Required.
{ "type": "string", "format": "uuid"}project
Section titled “project”Location: path. Required.
{ "type": "string", "format": "uuid"}Location: path. Required.
{ "type": "string", "format": "uuid"}Request body
Section titled “Request body”No request body is declared.
Responses
Section titled “Responses”HTTP 201
Section titled “HTTP 201”Issued key identity and one-time secret.
Response headers:
{ "Cache-Control": { "description": "Secrets must not be cached.", "schema": { "type": "string", "const": "no-store" } }}Content type: application/json.
{ "type": "object", "required": [ "id", "token" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "description": "One-time workspace API key secret; store securely. Never present in key metadata reads." } }}HTTP 401
Section titled “HTTP 401”Invalid or expired administrative credential.
Content type: application/json.
{ "type": "object", "required": [ "error" ], "description": "Gateway application error envelope. This does not describe framework body/path parsing failures or a proxy-generated response. Branch on error.type and HTTP status rather than matching message text.", "properties": { "error": { "type": "object", "required": [ "message", "type", "param", "code" ], "properties": { "message": { "type": "string", "description": "Safe human-readable explanation; not a stable programmatic identifier." }, "type": { "type": "string", "description": "Machine-readable failure category; new categories may be added." }, "param": { "type": "null" }, "code": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code, not a separate application error number." } } } }}HTTP 403
Section titled “HTTP 403”Workspace write permission required.
Content type: application/json.
{ "type": "object", "required": [ "error" ], "description": "Gateway application error envelope. This does not describe framework body/path parsing failures or a proxy-generated response. Branch on error.type and HTTP status rather than matching message text.", "properties": { "error": { "type": "object", "required": [ "message", "type", "param", "code" ], "properties": { "message": { "type": "string", "description": "Safe human-readable explanation; not a stable programmatic identifier." }, "type": { "type": "string", "description": "Machine-readable failure category; new categories may be added." }, "param": { "type": "null" }, "code": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code, not a separate application error number." } } } }}HTTP 404
Section titled “HTTP 404”Workspace outside authorized scope.
Content type: application/json.
{ "type": "object", "required": [ "error" ], "description": "Gateway application error envelope. This does not describe framework body/path parsing failures or a proxy-generated response. Branch on error.type and HTTP status rather than matching message text.", "properties": { "error": { "type": "object", "required": [ "message", "type", "param", "code" ], "properties": { "message": { "type": "string", "description": "Safe human-readable explanation; not a stable programmatic identifier." }, "type": { "type": "string", "description": "Machine-readable failure category; new categories may be added." }, "param": { "type": "null" }, "code": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code, not a separate application error number." } } } }}HTTP 409
Section titled “HTTP 409”Key is absent, revoked, expired or concurrently rotated.
Content type: application/json.
{ "type": "object", "required": [ "error" ], "description": "Gateway application error envelope. This does not describe framework body/path parsing failures or a proxy-generated response. Branch on error.type and HTTP status rather than matching message text.", "properties": { "error": { "type": "object", "required": [ "message", "type", "param", "code" ], "properties": { "message": { "type": "string", "description": "Safe human-readable explanation; not a stable programmatic identifier." }, "type": { "type": "string", "description": "Machine-readable failure category; new categories may be added." }, "param": { "type": "null" }, "code": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code, not a separate application error number." } } } }}Behavior and supported scope
Section titled “Behavior and supported scope”Requires workspace write access. Workspace API keys do not authorize these management operations. Revokes the old secret atomically. The replacement preserves grants, expiry, spending identity and configured key policies; rotation does not reset consumed allowance.
Supported scope: implemented