List and modify your keys

Inventory of your API keys

Over time, your team accumulates API keys for different environments, projects, and team members. The Management API lets you list all active keys, filter by permissions, and modify their settings without recreating them.

List keys

This endpoint is the starting point for any access audit, and it’s often where you discover the real inventory: keys created for a test eight months ago, a key under the name of a former team member, two production keys where no one knows which one is in use. List before you create anything new—the key you need might already exist.

curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Request parameters

• pageSize: number of keys per page (by default, all keys are returned)
• paginationToken: token to retrieve the next page if the number of keys exceeds the page size
• aclFilters: filter keys by specific permissions

Filter by ACL

You can retrieve only keys with a certain access level:

# List only keys with chat access
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

This filtering is what makes an audit manageable beyond a dozen keys. Two questions come up in practice and are answered by a single request: who can call the most expensive model, and which keys still carry a wildcard. The second is the most useful—a forgotten wildcard in production is the most common configuration error, and the quietest.

Pagination

For teams with many keys, use pagination:

# First page of 10 keys
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

# Next page with the received token
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Modify an existing key

Modifying rather than recreating is not just a convenience: the secret key stays the same, so no deployment is necessary. This lets you adjust limits or restrict permissions without service interruption—and, in case of suspicion, reduce a key’s rights in seconds while you prepare its rotation.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v3",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning"
    ],
    "qps": 30,
    "qpm": 1000,
    "tpm": 3000000
  }'

What you can modify

• name: rename the key to reflect a change in usage
• acls: add or remove permissions (endpoints, models)
• qps / qpm / tpm: adjust rate limits
• expireTime: extend or shorten the validity period

What you cannot modify

• The key identifier (api_key_id) remains fixed
• The secret key does not change during modification (use rotation for that)
• The owning team cannot be transferred

Check propagation

Here’s the detail that explains half the “bugs” reported after a key modification: the change is not instant across all servers. A freshly created key might return 401 for a few moments, an expanded ACL might not be active yet—and you look for the error in your own code when you just needed to wait. The propagation endpoint exists precisely to remove this doubt:

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

This endpoint returns the key’s propagation status. Wait for propagation to complete before using the key in production, especially after modifying ACLs.

Common scenarios

Upgrade a dev key to prod

Moving to production is the most common modification scenario, and the reflex to create a new key on this occasion is costly: you have to deploy it everywhere, update vaults, and the old one lingers indefinitely. Raising the limits on the existing key avoids all this.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-chatbot",
    "qps": 50,
    "qpm": 2000,
    "tpm": 5000000
  }'

Restrict a suspected compromised key

In case of suspicion, the order of operations matters. Restrict first—empty ACLs, zero rate limits—stops the bleed in one request, without breaking anything irreversibly. Rotation comes later, offline, once you have identified where the key was used. The reverse leaves you with production down and an investigation to conduct under pressure.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "acls": [],
    "qps": 0,
    "qpm": 0
  }'

Key takeaways

• GET /auth/teams/{teamId}/api-keys lists all keys with pagination and ACL filtering
• PUT /auth/api-keys/{apiKeyId} modifies parameters without changing the secret key
• GET /auth/api-keys/{apiKeyId}/propagation verifies that changes are effective
• Use ACL filtering to regularly audit your team’s access
• After any modification, check propagation before using the key in production