Key controls: model list, IP addresses, scopes and rotation
A key can carry restrictions of its own: only certain models, only from certain IP addresses, only for model calls or only for reading reports, and a rate limit lower than the account's. A key can be rotated: a new secret is issued and the old one works until the grace period ends. None of this is on by default; a key with no restriction behaves as before. A request that meets a restriction answers 403 and is not billed.
Last updated:
A key's controls
| Field | Default | Meaning |
|---|---|---|
allowed_models | Default:Empty: every model | Meaning:Up to 100 exact model ids, or a prefix ending in * (such as claude-*) |
allowed_ips | Default:Empty: any address | Meaning:Up to 50 IPv4 or IPv6 addresses or CIDR ranges |
scope | Default:full | Meaning:full, inference or usage |
rate_limit_per_min | Default:Empty: the account's limit | Meaning:The key's own rate limit, from one up to the account's limit |
These are set when a key is created or edited on the API keys page. In the account API each key has a controls object with the same fields, plus effective_rate_limit_per_min (the figure of the X-RateLimit-Limit header), rotated_at and previous_secret_expires_at.
The model list
- When a key has a model list and the request's model is not on it, the answer is
403with codekey_model_not_allowed. Nothing is held, billed or sent. - It is checked on every billed route: chat, Responses, embeddings, images, audio, video, the realtime client secret, the Anthropic route and the Gemini route (the model in the path).
GET /v1/models, polling and downloading results are not restricted.- In Anthropic message batches the model of every request is checked at submit, and the whole batch is refused when one is not on the list. Such a key may
POSTonly the submit and/{id}/cancelunder/anthropic/v1/messages/batches. - A key with a model list must name its model once: a JSON body with two
modelkeys (in any letter case) or a multipart form with twomodelparts answers400with codeinvalid_request; in a batch,requests, eachparamsand eachmodellikewise. - Matching against the list ignores letter case, but the price list does not: an id spelled with capitals (such as
GPT-4o-mini) passes the key's list and then answers402with codemodel_not_priced. Always write a model id asGET /v1/modelsreturns it. - A vendor prefix (
openai/gpt-4o) or a longer id (a dated snapshot) does not match the short id; use a*prefix for a family. - A retired id that is served by its successor is allowed when either id is on the list.
The address list
- A request from an address not on the key's list answers
403with codekey_ip_not_allowedon every route, and does not count toward the rate limit. - The address is the one our server sees for the connection; headers such as
X-Forwarded-Forsent by the client are ignored. - A key with an address list works on
https://1xai.ironly. Onhttps://api.1xai.irthe caller's address is not known to the gateway, and such a key answerskey_ip_not_allowedthere. - Private and loopback addresses and a
/0range are refused.
Scopes
| Scope | What it can do |
|---|---|
full | What it can do:Every route; how every key behaved before |
inference | What it can do:Everything except the account API |
usage | What it can do:Only GET on the account API (/v1/usage, /v1/usage/summary, /v1/usage/export, /v1/wallet/*, /v1/keys, /v1/keys/{id}, /v1/keys/current and /v1/sla/credits); no model call and no GET /v1/models |
Outside its scope a key answers 403 with code key_scope_denied. A usage key suits a finance dashboard or a reporting script: even if it leaks, it cannot spend.
A key's own rate limit
A key's own limit cannot be higher than the account's. The X-RateLimit-Limit header states the limit applied to the key now (rate limits).
Rotation
- Rotation issues a new secret for the same key: its id, name, controls, expiry, spend cap, spend so far and usage history stay. The new secret is shown once.
- The old secret works until the grace period ends: from zero to 168 hours, 24 by default. With a grace of zero it stops at once.
- Rotating again stops an old secret that is still in its grace at once. Revoking the key stops both secrets.
- A revoked or expired key cannot be rotated (
409with codekey_not_active).
The order of checks, and the error codes
The order: first 401 (a wrong, revoked, expired or capped key), then key_ip_not_allowed, then key_scope_denied, then 429, then the route's own checks, among them key_model_not_allowed.
| Status | Code | When |
|---|---|---|
403 | Code:key_model_not_allowed | When:The model is not on the key's list |
403 | Code:key_ip_not_allowed | When:The caller's address is not on the key's list |
403 | Code:key_scope_denied | When:The route is outside the key's scope |
1xAi is an independent gateway. It is not affiliated with, endorsed by, or a reseller for OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot AI, Z.ai, Alibaba Qwen, MiniMax or Tencent Hunyuan. Requests are relayed upstream rather than answered by models of our own, so each provider's own usage policies apply to what their models will and will not do, and their model availability is theirs to change. Current reachability is published on the status page.