1. Docs
  2. API Reference
  3. Rotate an API key's secret

Rotate an API key's secret

POST/api/v1/api-keys/{id}/rotate-secret

Rotates the secret of an existing API key in place, minting a brand-new cnpy_-prefixed value for the same row while preserving its id, name, scopes, access_mode, expiry, and audit lineage. The previous secret is invalidated immediately and the new plaintext is returned exactly once in the key field. is_active is left untouched — rotating does not re-enable a disabled key. Returns 404 when no key with the given id exists in the active Environment. A scoped API key can act only on scoped keys whose scopes it holds itself; any other key is refused with 403.

Authentication

Bearer TokenAuthorization Option A

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

API KeyX-API-Key Option B

API key for management-tier access. Never send alongside an Authorization header: a request carrying both is refused.

Path Parameters

idstring Required

Responses

application/json

  • dataApiKeyCreatedResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Errors

When the request can't be completed, the response body includes a stable error code you can branch on, and a correlation_id (also sent as the X-Correlation-Id header). Quote the correlation id when you contact support: it identifies the exact request in Canopy's logs.

403api_key.access_exceeds_callerForbidden
When it happens

The caller is a scoped API key asking for more than it holds, or acting on a key that has more: a full-access key, or a scope outside its own. Applies to creating, rotating, enabling, disabling and deleting keys.

Remediation

Request only scopes the calling key already holds, or make the change from the Console or with a full-access key.

Returned object

ApiKeyCreatedResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/api/v1/api-keys/value/rotate-secret" \
  -H "X-API-Key: $CANOPY_API_KEY"
Response
{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "key": "string",
    "key_preview": "string",
    "access_mode": "scoped",
    "scopes": [
      "string"
    ],
    "expires_at": "2026-04-20T12:00:00.000Z",
    "created_at": "2026-04-20T12:00:00.000Z"
  }
}
 Related endpoints
GETList API keys for Application
POSTCreate a new API key
PATCHActivate or deactivate an API key
DELETEDelete an API key
 Was this page helpful?

Tell us how we can improve this guide.

Canopy