Key rotation and deletion

Rotation: Renew without interruption

Key rotation is a critical security practice. It generates a new secret key to replace the old one without deleting the key itself. The old secret is immediately and permanently invalidated.

Perform a rotation

Rotation solves a problem deletion cannot: renewing the secret without losing the key’s identity. Its ACLs, rate limits, and name survive the operation, so you don’t need to reconfigure anything—only the secret changes in your vault. This makes regular rotation practical; recreating a key would require reconfiguring everything every time.

POST /auth/api-keys/{apiKeyId}/rotate

curl -X POST "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/rotate" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Rotation behavior

• The old secret key is immediately invalidated—any requests using it will fail with a 401 error
• A new secret key is generated and returned in the response
• The key ID (apiKeyId), name, ACLs, and rate limits remain unchanged
• The new secret key is displayed only once—store it immediately

Secure rotation process

One part of this procedure deserves emphasis because it often surprises users: the old secret is invalidated immediately. There is no grace period where both secrets work. Any services still using the old value will fail the second after the call. This dictates the order of the six steps below: prepare your vault before triggering the rotation, not after.

1. Prepare your infrastructure to accept a new key (environment variable, vault)
2. Perform the rotation via the API
3. Update the secret in your vault immediately
4. Redeploy your services with the new key
5. Verify that requests succeed with the new key
6. Verify propagation via GET /auth/api-keys/{apiKeyId}/propagation

When to rotate

Three situations trigger rotation, each with different urgency. Suspected leakage requires immediate rotation: a team member with key access leaves, a log containing a key is exposed publicly, or a Git repository contains a plaintext key. In these cases, every hour of waiting is an hour of exposure, so rotate before completing the incident analysis. Policy-based rotation is preventive: every 30, 60, or 90 days, depending on your security requirements, it limits the lifespan of a key that might have leaked unnoticed. Finally, environment changes—infrastructure migration or provider switches—are a natural opportunity to start fresh with clean keys rather than carrying old ones into a context they were never designed for.

Delete a key

Deletion is permanent and irrevocable. The question to ask before deleting isn’t “Is this key compromised?” but “Do I still need this access scope?” If the answer is yes, you need rotation: it neutralizes the exposed secret while preserving the configuration. Deletion is only justified for a key that is no longer useful—a stopped project, a departed vendor, or a decommissioned environment.

DELETE /auth/api-keys/{apiKeyId}

curl -X DELETE "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Consequences of deletion

• The key and all its parameters are permanently deleted
• All requests using this key will fail immediately
• The action is irreversible—you will need to create a new key with new parameters
• The key’s usage history remains available in analytics

Rotation vs. deletion

Automate rotation

Automated rotation only makes sense if writing to the vault is part of the same script, with no manual intervention in between. Otherwise, you simply shift the risk: a machine-generated secret copied by hand is more likely to end up in a clipboard or terminal history than a key created from the console.

import requests
import json

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"

# Rotate
response = requests.post(
    f"{MANAGEMENT_API}/auth/api-keys/{KEY_ID}/rotate",
    headers={"Authorization": f"Bearer {MGMT_KEY}"}
)

new_key = response.json()
new_secret = new_key.get("secret")

# Store in your vault (example with a .env file)
# In production, use Vault, AWS Secrets Manager, etc.
print(f"New key generated. Update your vault.")

Scheduled rotation

Integrate rotation into your CI/CD pipeline or a cron job:

# Cron example: rotation on the 1st of each month at 3 AM
0 3 1 * * /opt/scripts/rotate-xai-keys.sh

Key takeaways

• POST /auth/api-keys/{apiKeyId}/rotate invalidates the old secret and generates a new one
• Old secret invalidation is immediate and permanent
• DELETE /auth/api-keys/{apiKeyId} deletes the key irreversibly
• Prefer rotation over deletion to maintain existing ACLs and limits
• Automate rotation with a script and a secrets vault
• Always verify propagation after a rotation