Rotate an xAI API key via the Management API

Rotate an inference API key secret over HTTP when a leak, scheduled rotation, or staff handoff requires a new secret without deleting the key id your systems already reference. Official Accounts and Authorization documents POST /auth/api-keys/{apiKeyId}/rotate on https://management-api.x.ai, authorized with a management key. The call permanently invalidates the old secret after an optional grace window, returns the new secret once in the apiKey field, and keeps the same apiKeyId, ACLs, and rate limits. Mint the management key first with Create a management key in the xAI Console if you do not already have one.

What you need

A management key that can call auth routes for the team, the apiKeyId of the inference key to rotate (from list or create responses), and a place to store the new secret immediately because the full value appears only on create or rotate. Optional body fields are expireTime for the new secret and oldSecretExpireTime for when the old secret stops being accepted. Docs default oldSecretExpireTime to twenty-four hours from now for non-expired keys and cap that grace at seven days. For click-through disable and delete without a Management rotate call, use Rotate or disable an xAI API key. Neighboring programmatic key work lives in Manage API keys with the xAI Management API. More API jobs live on the API hub.

Call the rotate endpoint

1. Export the management key and target inference key id outside of source control:

export XAI_MANAGEMENT_KEY="your_management_key"
export XAI_API_KEY_ID="your_api_key_id"

2. Rotate with the default grace window (old secret accepted for about twenty-four hours unless you override):

curl "https://management-api.x.ai/auth/api-keys/${XAI_API_KEY_ID}/rotate" \
  -X POST \
  -H "Authorization: Bearer ${XAI_MANAGEMENT_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

3. Copy the new secret from the response apiKey field into your secret store and update every client that still holds the old value before the grace window ends. The response also repeats apiKeyId, redactedApiKey, ACL strings, and rate-limit fields so you can confirm the identity of the key you rotated.

4. When you need an explicit cutover, set oldSecretExpireTime (ISO 8601) to a time no more than seven days ahead, and optionally set expireTime if the new secret should expire on a different schedule than the previous one:

curl "https://management-api.x.ai/auth/api-keys/${XAI_API_KEY_ID}/rotate" \
  -X POST \
  -H "Authorization: Bearer ${XAI_MANAGEMENT_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "oldSecretExpireTime": "2026-09-28T20:00:00Z",
    "expireTime": "2027-09-27T00:00:00Z"
  }'

5. After cutover, confirm propagation across clusters with the sibling propagation check documented in the Management auth reference (GET /auth/api-keys/{apiKeyId}/propagation) before you declare the rotation complete for multi-region traffic.

Keep the call on https://management-api.x.ai. An inference Bearer against https://api.x.ai cannot rotate keys.

Prove the new secret works

Send a cheap authenticated request with the new secret against the inference host your key is allowed to use, then confirm the old secret still works only until oldSecretExpireTime. After that timestamp, expect auth failures on the retired secret. If your Security FAQ workflow prefers Console disable-then-create instead of in-place rotate, follow Rotate or disable an xAI API key and update every consumer to the newly created key id.

Pitfalls

Leaving the rotate response without copying apiKey forces another rotate because the Management API will not redisplay the full secret later. Setting oldSecretExpireTime more than seven days out is rejected by the documented constraint, while omitting it and assuming the old secret dies instantly breaks rolling deploys that still need the default day of overlap. Rotating the wrong apiKeyId after listing keys on a multi-key team invalidates a secret that production still holds. Using an inference key as the Bearer on the management host returns auth errors that look like a missing rotate route. Skipping the propagation check after rotate can leave one cluster accepting traffic on stale cache until the new secret is fully distributed.