API Keys / Tokens

POST/v1/orgs/{org_id}/tokens/{key_id}/rotate

Rotate Token

Rotate a token: deactivate old, create new with same scope.

Bearer token or X-API-Keyscope: adminoperation_id: tokens.rotate

Authentication

Send either Authorization: Bearer <token> or X-API-Key: <token>. The caller must hold the "admin" role on the organization. Admin token — create via POST /v1/orgs/{org_id}/tokens/admin. Org-wide scope, so keep it tightly held. Requests without a valid credential are rejected with 401.

SDK install

pip install znyx-sdknpm install @znyx/sdk

Code samples

Request

curl -X POST "$ZNYX_API_URL/v1/orgs/00000000-0000-0000-0000-000000000000/tokens/00000000-0000-0000-0000-000000000000/rotate" \
  -H "Authorization: Bearer $ZNYX_TOKEN"

Response

application/json

Successful Response

{
  "id": 0,
  "key_prefix": "string",
  "key_type": "string",
  "org_id": null,
  "project_id": null,
  "environment_id": null,
  "scopes": [
    "string"
  ],
  "is_active": false,
  "expires_at": null,
  "created_at": "string",
  "raw_key": "string"
}

Schema: object

Path parameters

Name	Type	Required	Description
org_id#path	string	required	-
key_id#path	integer	required	-

Header parameters

Name	Type	Required	Description
X-API-Key#header	string \| null	optional	-
authorization#header	string \| null	optional	-

Responses

Status	Description
200	Successful Response
422	Validation Error

Response schema

idrequiredinteger

key_prefixrequiredstring

key_typerequiredstring

org_idstring | null

project_idstring | null

environment_idstring | null

scopesstring[]

is_activerequiredboolean

expires_atstring | null

created_atrequiredstring

raw_keyrequiredstring

Errors & what triggers them

Code	Trigger	Fix
401	Missing or expired Authorization header.	-
403	Token does not have the required role (admin / editor).	-
404	Target resource does not exist in this org.	-
422	Request body failed validation.	-

Notes & examples

When to use this

Runtime token collision — POST /tokens/runtime returned 409 because one already exists. Rotate returns a fresh raw value.
Scheduled rotation — every 90 days for admin tokens, per your security runbook.
Suspected compromise — rotate immediately. The old token is deactivated atomically with the new one coming online.

No grace period on this endpoint

This endpoint deactivates the old key the instant the new one is created. If your workloads need a rollout window (distributed deploys picking up new config), see the key-rotation flow — different shape, supports a configurable grace period.

What stays the same

Same key_type (runtime / admin / ci).
Same project_id / environment_id scope.
Same scopes list.

Only the raw token value and key_prefix change. Consumers storing the prefix (most dashboards do) need to refresh.

POST /v1/orgs/{org_id}/tokens/runtime — create a new token from scratch.
DELETE /v1/orgs/{org_id}/tokens/{key_id} — revoke without replacement.