Create and configure an API key

Why create keys via the API

Creating a key manually takes thirty seconds—which is exactly why you need automation. Because it’s fast, you do it without thinking: no naming convention, no rate limits, just a wildcard “to move fast.” Six months later, no one knows what key does what.

Using the API forces you to name, scope, and cap every key because these are script parameters. Consistency stops being a discipline you have to maintain and becomes a property of the code. You can automate key creation for your environments (dev, staging, production), apply granular ACLs, and define rate limits—all within your deployment scripts or infrastructure tools.

Creation endpoint

To create an API key, send a POST request to the following endpoint:

POST /auth/teams/{teamId}/api-keys

Request body

{
  "name": "ma-cle-production",
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 10,
  "qpm": 100,
  "tpm": 1000000,
  "expireTime": "2026-12-31T23:59:59Z"
}

Detailed parameters

name (required): a readable identifier for your key. Choose a descriptive name that indicates usage (prod-backend, staging-chatbot, dev-john). This name appears in the console and in usage logs.

acls (required): the list of permissions granted to this key. Two formats are available:

• api-key:endpoint:[endpoint] — restricts accessible endpoints (chat, embed, image, models, sample, tokenize, documents)
• api-key:model:[model] — restricts usable models (grok-4.20-0309-reasoning, grok-4.3, etc.)

The * character acts as a wildcard: api-key:endpoint:* authorizes all endpoints, api-key:model:* all models. Reserve this for local development. In production, a wildcard means a compromised key gives access to everything your team can do—including the most costly models, which your application may never use.

qps (optional): queries per second — maximum number of requests per second.

qpm (optional): queries per minute — maximum number of requests per minute.

tpm (optional): tokens per minute — maximum number of tokens processed per minute.

expireTime (optional): expiration date in ISO 8601 format. The key will automatically disable on this date.

Complete example with curl

curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v2",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning",
      "api-key:model:grok-4.3"
    ],
    "qps": 20,
    "qpm": 500,
    "tpm": 2000000,
    "expireTime": "2027-06-30T23:59:59Z"
  }'

The response contains the secret key, which will never be displayed again. This rule has a practical consequence you need to anticipate before running the script, not after: if you create keys in a loop, storage must happen in the same motion. A key lost between creation and registration is not recoverable—you must delete it and start over. Write it to a vault (Vault, AWS Secrets Manager) rather than to your terminal’s standard output, where it will end up in your history.

Recommended ACL strategies

Development key (broad)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 5,
  "qpm": 50
}

Ideal for local development: access is broad because you don’t know in advance what you’ll try, but rate limits stay low. This is the right compromise—an infinite loop written by mistake on a Friday night will cost a few cents instead of a few hundred euros.

Production key (restricted)

{
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 50,
  "qpm": 2000,
  "tpm": 5000000
}

In production, the rule reverses: start from what the application actually does and authorize only that. The question to ask when writing the ACL is always the same—if this key leaks tomorrow, what can a third party do with it? A key limited to chat on a single model and capped at ten requests per second gives a short answer.

Temporary key (expirable)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "expireTime": "2026-04-10T00:00:00Z"
}

Automatic expiration solves the problem no one handles: keys people forget to delete. A POC, a demonstration, a passing contractor—in all these cases, expireTime guarantees access turns itself off. This is the only reliable way to maintain a clean inventory, because it doesn’t rely on anyone’s memory.

Available ACL endpoints

To see the endpoints you can use in ACLs, consult:

GET /auth/teams/{teamId}/endpoints

The available endpoints are: chat, embed, image, models, sample, tokenize, documents. This list may evolve over time, so check regularly.

Key takeaways

• Key creation happens via POST /auth/teams/{teamId}/api-keys
• ACLs follow the format api-key:endpoint:[name] or api-key:model:[name]
• The wildcard * grants full access to all endpoints or models
• The secret key is displayed only once at creation—save it immediately
• Always define rate limits (qps, qpm, tpm) suited to usage
• Use expireTime for temporary keys