Key rotation and lifecycle

Why key rotation is essential

A common objection in training sessions is: “My key has never leaked, why change it?” The answer comes down to one word: uncertainty. You can never prove a key hasn’t been exposed—a verbose log forgotten on a server, a screenshot shared in a support ticket, a compromised developer workstation from six months ago. Regular rotation turns this uncertainty into bounded risk: even if a key was copied without your knowledge, it will stop working at the next rotation. This is exactly the reasoning SOC 2 auditors use; they expect a documented rotation policy. This is what we call reducing the temporal attack surface: the longer a key lives, the longer the window of exploitation for a silent compromise.

xAI’s Management API is designed to make this practice painless: it provides a dedicated endpoint that lets you rotate a key without rewriting your configurations.

Rotation via the Management API

The rotation endpoint is straightforward:

POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate

Make sure you understand what this call does before using it: it generates a new secret key for the existing ID and permanently invalidates the old one, while keeping the ACLs, rate limits, and configurations attached to the key. The thing that catches teams off guard the first time is that the change is immediate and irreversible. If your production backend is using this key when you trigger the rotation, it will start receiving authentication errors within seconds. There is no grace period, no way to roll back.

That’s why, in production, you generally prefer a two-step procedure to avoid any interruption. First, create a new key via POST /auth/teams/{teamId}/api-keys, with exactly the same permissions as the old one. Then verify its propagation with GET /auth/api-keys/{newKeyId}/propagation—a freshly created key isn’t instantly known across the entire infrastructure, and deploying too early produces confusing errors. Next, deploy the new key to your backends and test that calls actually work with it, not just that the deployment finished without errors. Only once you have this confirmation should you disable the old key, or let it reach its expiration, before permanently deleting it with DELETE /auth/api-keys/{oldKeyId}.

This “new key then delete” approach gives you an overlap period where both keys coexist: if deployment fails on one server, nothing breaks. In-place rotation remains available if you want to keep the same key ID:

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

In this case, plan to update your backends immediately, since the old key dies the instant the call completes.

The complete lifecycle of a key

A well-managed key has a four-act story. At creation, via POST /auth/teams/{teamId}/api-keys, you define its name, its ACLs, and—this is the habit to cement—its expiration date:

{
  "name": "prod-chat-service",
  "acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
  "expireTime": "2026-12-31T23:59:59Z"
}

A key without expireTime is a key that will live forever if no one thinks about it; a key with expiration forces your team to ask the question of renewal on a fixed date. Next comes monitoring: GET /v1/api-key tells you the key status (api_key_blocked, api_key_disabled), and the xAI console exposes usage and anomalies. For mid-life modifications—renaming, adjusting ACLs, tightening rate limits, pushing back expiration—use PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. Finally, deletion, DELETE /auth/api-keys/{apiKeyId}, is permanent and irreversible: any application using this key stops working instantly. Before deleting, ensure no forgotten service—a monthly cron, a reporting script—still depends on it.

Which rotation strategy should you adopt?

The right frequency depends on the sensitivity of your environment. Monthly rotation is mandatory in highly sensitive contexts like finance or healthcare, where the exposure window must remain minimal. Quarterly rotation suits standard professional environments: frequent enough to be effective, spaced enough not to burden teams. Annual rotation, coupled with a defined expiration date, is the acceptable minimum—below that, your rotation policy isn’t really a policy. In all cases, automation via a scheduled script saves you from depending on an administrator’s memory.

Event-driven rotation adds to this schedule, triggered by circumstances rather than date. You will most often trigger it upon the departure of an employee who had access to keys: even if the separation is cordial, the key they knew must rotate the same day—this is a security hygiene rule, not a sign of distrust. Do the same in case of suspected compromise, a security incident in your infrastructure, or a vendor change who had access to your systems.

Twenty minutes to regain control of your inventory

The best time to discover the real state of your keys isn’t audit day. So list all your keys now with GET /auth/teams/{teamId}/api-keys and identify those without expiration, to add an expireTime. For each one, ask yourself if its ACLs match the strict minimum required by the application using it; a key created for a prototype and recycled into production almost always carries too many rights.

Then delete unused keys, because every active key is a potential attack vector, and a key no one remembers is the worst of all: no one will notice its abnormal use. Finish by documenting who has access to which key and why. This document, more than the keys themselves, is what you will pull out at the next audit.

Key takeaways

• The POST /auth/api-keys/{id}/rotate endpoint invalidates the old key permanently, with no grace period
• In production, prefer creating a new key then deleting the old one to avoid any interruption
• Always set an expiration date on your keys
• Automate rotation with a scheduled script (monthly, quarterly, or annually based on sensitivity)
• Trigger immediate rotation upon any personnel change or security incident