IN ENGLISH · API DOCS

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:

[01]KEY CONTROLS

A key's controls

The `controls` fields
FieldDefaultMeaning
allowed_modelsDefault:Empty: every modelMeaning:Up to 100 exact model ids, or a prefix ending in * (such as claude-*)
allowed_ipsDefault:Empty: any addressMeaning:Up to 50 IPv4 or IPv6 addresses or CIDR ranges
scopeDefault:fullMeaning:full, inference or usage
rate_limit_per_minDefault:Empty: the account's limitMeaning: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.

[02]KEY CONTROLS

The model list

  • When a key has a model list and the request's model is not on it, the answer is 403 with code key_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 POST only the submit and /{id}/cancel under /anthropic/v1/messages/batches.
  • A key with a model list must name its model once: a JSON body with two model keys (in any letter case) or a multipart form with two model parts answers 400 with code invalid_request; in a batch, requests, each params and each model likewise.
  • 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 answers 402 with code model_not_priced. Always write a model id as GET /v1/models returns 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.
[03]KEY CONTROLS

The address list

  • A request from an address not on the key's list answers 403 with code key_ip_not_allowed on 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-For sent by the client are ignored.
  • A key with an address list works on https://1xai.ir only. On https://api.1xai.ir the caller's address is not known to the gateway, and such a key answers key_ip_not_allowed there.
  • Private and loopback addresses and a /0 range are refused.
[04]KEY CONTROLS

Scopes

Scopes
ScopeWhat it can do
fullWhat it can do:Every route; how every key behaved before
inferenceWhat it can do:Everything except the account API
usageWhat 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.

[05]KEY CONTROLS

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).

[06]KEY CONTROLS

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 (409 with code key_not_active).
[07]KEY CONTROLS

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.

Key-restriction error codes
StatusCodeWhen
403Code:key_model_not_allowedWhen:The model is not on the key's list
403Code:key_ip_not_allowedWhen:The caller's address is not on the key's list
403Code:key_scope_deniedWhen: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.