1. Docs
  2. API Reference
  3. Activate or deactivate an API key

Activate or deactivate an API key

PATCH/api/v1/api-keys/{id}

Enables or disables an existing API key in the current Environment via the is_active flag. Disabling is reversible: a disabled key is rejected by authentication immediately and can be re-enabled later. Returns the key's metadata with no secret. 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

Request body

application/json

is_activeboolean Required

Whether the key is active. Set `false` to deactivate (the key stops authenticating immediately, reversibly); set `true` to reactivate.

Responses

application/json

  • dataApiKeyResponseDto*

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

ApiKeyResponseDtoView all properties on this resource
Request
curl -X PATCH "https://auth.canopy-io.com/api/v1/api-keys/value" \
  -H "X-API-Key: $CANOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'
Response
{
  "data": {
    "id": "string",
    "client_id": "string",
    "name": "string",
    "description": "string",
    "key_preview": "string",
    "access_mode": "scoped",
    "scopes": [
      "string"
    ],
    "is_active": false,
    "last_used_at": "2026-04-20T12:00:00.000Z",
    "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
DELETEDelete an API key
POSTRotate an API key's secret
 Was this page helpful?

Tell us how we can improve this guide.

Canopy