IN ENGLISH · API DOCS

API keys and security

An API key starts with 1xai-, is shown once when it is created, and only its SHA-256 hash is stored. Each key can have an expiry (at least 12 hours) and a spend cap in Toman; a key that reaches its cap revokes itself. Request and response text stays next to the usage report for up to 30 days. Your IP address, User-Agent and key are never sent to a model vendor.

Last updated:

[01]API KEYS AND SECURITY

Key format and storage

  • A key is 1xai- followed by 32 random bytes (as base64url).
  • The full key is shown once, at the moment it is created. Copy it then.
  • We do not keep the key itself: only its SHA-256 hash and its first 13 characters, so that you can recognise it in the list. A lost key cannot be recovered: create a new one and revoke the old.
  • Every request is checked against the database, so a key you revoke is refused from its next request on. Requests already in flight finish.

Send the key in one of three headers; see authentication. A key in the URL (?key=) is not accepted.

[02]API KEYS AND SECURITY

Creating and revoking

Keys are created and revoked in the dashboard, on the API keys page (in Persian). At creation you can set:

Settings of a key
SettingValueWhen left empty
NameValue:Any text; shown beside each call in the usage reportWhen left empty:Unnamed
ExpiryValue:At least 12 hoursWhen left empty:Never expires
Spend capValue:An amount in TomanWhen left empty:No cap

Keys are created and revoked in the dashboard only. The account API reads keys and never returns a key itself.

[03]API KEYS AND SECURITY

Expiry

A key past its expiry answers 401 with code key_revoked. The expiry cannot be changed after creation: create a new key. For temporary work (a contractor, an experiment, a workshop) hand out a short-lived key, so that forgetting it costs nothing.

[04]API KEYS AND SECURITY

The spend cap: a key that revokes itself

  • The full cost of every billed call is added to that key's spend, whatever paid for it (wallet, plan credit or gift credit).
  • When a key's spend reaches its cap, the key is revoked at once. The next request answers 401, with code key_capped or key_revoked.
  • The cap is checked after each call settles. So the call that crosses it, and calls in flight at the same moment, complete and are billed: the final spend can pass the cap by the cost of those calls.
  • With limit alerts switched on, you get one email when a key's spend reaches 90% of its cap.
  • A revoked key is not reactivated. Create a new key with a new cap.
[05]API KEYS AND SECURITY

Alerts

Alerts are set on the top-up page (in Persian). Nothing is sent until you save them yourself.

Account alerts
AlertWhenChannel
Low balanceWhen:When the spendable balance falls under the threshold you setChannel:Verified email; SMS where it is available
Key capWhen:When a key's spend reaches 90% of its capChannel:Email
Plan allowanceWhen:When 90% of a plan's weekly, monthly or API allowance is usedChannel:Email

Each alert is sent once per crossing. The spendable balance is the spendable_toman of GET /v1/wallet/summary (see the account API).

[06]API KEYS AND SECURITY

What is logged, and for how long

Next to each usage record, the start of the request and of the response (up to 64 KB each) and, when it is longer, its last 16 KB are kept so that you can read them in your own usage report. That text is erased after 30 days. The numbers (model, tokens, cost, status and time) stay for accounting.

What is kept for each call
DataKept
Model, vendor, route, tokens, cost in USD and Toman, the rate used, status, request id, time, key nameKept:With no erasure date, for accounting and disputes
The start of the request and response text (up to 64 KB) and its last 16 KBKept:30 days
The audio file of a transcription, and the audio of a realtime callKept:Not kept
A generated image (base64) in a responseKept:Removed from the logged text

You read that text yourself in the dashboard (the call log) and with GET /v1/usage; through an API key, only the text of calls made with an API key is returned, never what was written in the chat (what each key reads). There is no switch in this release to turn body logging off for a key. The privacy policy is the full reference.

[07]API KEYS AND SECURITY

What reaches the model vendor

Your request is sent again from our server with a key of our own. Of your headers only these pass; every other header is dropped:

Headers forwarded to the vendor
RouteHeaders forwarded
/v1/*Headers forwarded:Content-Type, Accept, OpenAI-Organization, OpenAI-Project, OpenAI-Beta
/anthropic/*, /v1/messagesHeaders forwarded:Content-Type, Accept, anthropic-version, anthropic-beta
/gemini/*Headers forwarded:Content-Type, Accept
  • Never sent: your IP address (and X-Forwarded-For and its relatives), User-Agent, cookies, Referer, Origin, Accept-Language, and your 1xai-* key.
  • The request body is the one you sent, except for a short list of changes given under OpenAI-compatible endpoints (for example store: false on OpenAI models).
  • The request text goes to the vendor of the model you chose, and that vendor's own data-retention policy applies to it.
[08]API KEYS AND SECURITY

Good practice

  • Create a separate, named key per application and per environment (test, production); the usage report shows each call with its key's name.
  • Put a spend cap and an expiry on test keys.
  • Never put a key in browser code or a mobile app. For a voice call from a browser, mint a short-lived secret (realtime voice).
  • To replace a key: create a new one, update the application, then revoke the old one.
  • For a team, use a company account with workspaces instead of passing one key around.

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.