Rotate an API key | ToAPIs Documentation

POST

/api/v1/api-keys/{api_key_id}/rotate

Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.

Behavior

Generates a new secret for a given key, for secret leaks or periodic rotation. On success it returns the complete key. The original ID, name, status, expiry, credits, and restrictions are unchanged.

Disabled, expired, or exhausted keys can also be rotated, but rotation does not re-enable them. Revoked keys return 404. After a successful rotation the old secret stops working immediately — there is no overlap period in which both secrets are valid.

If you send several rotations for the same key concurrently, only the last submitted secret works and the others are invalidated at once, so run rotations serially.

Authentication

Authorizationstringheaderrequired

Use Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model keys are not accepted and X-User-Id is not required. See access rules.

Request parameters

api_key_idstringpathrequired

Decimal string ID of your ordinary model key, not the sk- secret.

A nonempty body requires Content-Type: application/json and is limited to 16384 bytes. It must be a JSON object. Unknown or duplicate fields and query parameters are rejected. Write bodies have a 10-second read deadline.

The body must be empty or {}.

Request examples

requestExample

curl --request POST \
  --url 'https://api.toapis.com/api/v1/api-keys/43/rotate' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

response = requests.post(
    "https://api.toapis.com/api/v1/api-keys/43/rotate",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys/43/rotate", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({}),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Response fields

Examples use fictitious data. See Get API key for key metadata and Access for the shared response and error contract.

data.keystring

Full secret including the sk- prefix, returned only by this create or rotate response.

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "id": "43",
    "name": "Example Key",
    "key_hint": "****new4",
    "status": "enabled",
    "created_at": "2026-11-01T08:00:00Z",
    "expires_at": "2027-01-01T00:00:00Z",
    "unlimited": false,
    "remaining_credits": "500",
    "daily_limit_credits": null,
    "monthly_limit_credits": null,
    "key": "sk-example11111111111111111111111111111111111111new4",
    "model_limits": [],
    "allow_ips": []
  }
}