Status: Management API DOCUMENTED + ACCOUNT_RESTRICTED — it needs a Management key (console → Settings → Management Keys) that this atlas does not have; two GET probes with the inference key returned 401 {"code": 16, "message": "Invalid bearer token. Please ensure you use a valid management key.", "details": []}. Account/catalogue endpoints on https://api.x.ai (/v1/api-key, /v1/me, /v1/models*, /v1/tokenize-text) are LIVE_VERIFIED. No destructive call was made.
Sources: https://docs.x.ai/developers/management-api-guide · /developers/rest-api-reference/management · …/management/{auth,billing,audit} · /developers/rest-api-reference/inference/{models,other} · /developers/faq/{security,team-management} · /console/{billing,usage} · sources/xai/openapi/openapi.json (/v1/me).
Last verified: 2026-09-18 · Machine-readable: generated/fragments/endpoints/xai-models-management.json (34 endpoint records).
# 1. Two hosts, two key types
|
Inference API |
Management API |
| Base URL |
https://api.x.ai (+ us.api.x.ai, mtls.api.x.ai, gRPC api.x.ai:443) |
https://management-api.x.ai |
| Credential |
API key xai-… (team-bound, created by a user, ACL-scoped) or OAuth token (/v1/me) |
Management key (scope SCOPE_TEAM or SCOPE_ORGANIZATION; requires the user to hold "Management Keys Read + Write") |
| Wrong key |
400 invalid-argument "Incorrect API key provided" (bogus) / 401 unauthenticated:no-credentials (missing) |
401 {code: 16, message, details} (gRPC-style) |
| Field style |
snake_case |
camelCase (apiKeyId, redactedApiKey, paginationToken) |
| Pricing |
per usage |
none documented |
# 2. Account & catalogue endpoints on api.x.ai (inference key)
| Endpoint |
Purpose |
Live 2026-09-19 |
GET /v1/api-key |
key metadata: redacted_api_key, name, user_id, team_id, acls[], api_key_id, create_time, modify_time, modified_by, api_key_blocked, api_key_disabled, team_blocked |
200; acls ["api-key:model:*","api-key:endpoint:*"]; create_time/modify_time = "" (docs promise timestamps) |
GET /v1/me |
caller identity (API key or OAuth): user_id, team_id, team_blocked, zdr_status (no_zdr | zdr; legacy pii_scrubbing), api_key{redacted_api_key, api_key_id, blocked, disabled} | oauth{client_id} — OpenAPI only, not on the docs pages |
200; zdr_status: "no_zdr" |
GET /v1/models, /v1/models/{id} |
catalogue with prices (ticks) and aliases; accepts aliases and retired redirect slugs |
200 (12 ids); grok-3 → grok-4.3 object |
GET /v1/language-models(/{id}), /v1/image-generation-models(/{id}), /v1/video-generation-models(/{id}), /v1/embedding-models(/{id}) |
typed catalogues (fingerprint, version, modalities, pricing matrix) |
200 / 200 / 200 / 200 (empty) ; grok-embedding-small → 404 |
POST /v1/tokenize-text |
{model, text, user?} → token_ids[{token_id, string_token, token_bytes}] |
200 (4 tokens for "Reply with OK."); text: 123 → 422 string body |
Also on api.x.ai (other agents): /v1/files*, /v1/skills*, /v1/responses*, /v1/videos/{id}.
# 3. Management API endpoints (management key)
# Accounts & authorization (/auth)
| Method |
Path |
Purpose |
Notes |
| GET |
/auth/management-keys/validation |
validate a management key → apiKeyId, scope, scopeId, ownerUserId, createTime, modifyTime (teamId deprecated) |
no ACL needed; probed → 401 with inference key |
| POST |
/auth/teams/{teamId}/api-keys |
create inference key: name*, acls[], qps, qpm, tpm (string), expireTime → apiKey (plaintext, once), apiKeyId, redactedApiKey, aclStrings… |
keys have no access by default: grant api-key:endpoint:* (or :chat, :image) and api-key:model:* (or :grok-4.6) |
| GET |
/auth/teams/{teamId}/api-keys |
list keys (pageSize, paginationToken, aclFilters[], activeOnly); admin sees all, member own |
probed → 401 |
| PUT |
/auth/api-keys/{api_key_id} |
selective update {apiKey:{…}, fieldMask:"qpm"} |
|
| POST |
/auth/api-keys/{apiKeyId}/rotate |
!!CAUTION!! rotate secret; oldSecretExpireTime default 24 h, max 7 d |
never run |
| DELETE |
/auth/api-keys/{apiKeyId} |
!!CAUTION!! permanent delete → {} |
never run |
| GET |
/auth/api-keys/{apiKeyId}/propagation |
icPropagation{ "cloud9.api.x.ai": true, "us-east-1.api.x.ai": true } |
new keys propagate to clusters with a delay |
| GET |
/auth/teams/{teamId}/models |
clusterConfigs[] per inference cluster with model lists (names for api-key:model: ACLs) |
large schema |
| GET |
/auth/teams/{teamId}/endpoints |
acls[{acl, description, namespace}] grantable to keys |
|
# Billing (/v1/billing/teams/{team_id}/…)
| Method |
Path suffix |
Purpose |
| GET / POST |
billing-info |
get / set billing address & tax info (invoices cannot be regenerated) |
| GET |
invoices |
list invoices (paginated) |
| GET |
payment-method |
list payment methods (add/delete only in console) |
| POST |
payment-method/default |
set default payment method |
| GET |
postpaid/invoice/preview |
amount due for the current postpaid period |
| GET / POST |
postpaid/spending-limits |
monthly invoiced-billing cap ($0 default = prepaid only) |
| GET |
prepaid/balance |
prepaid balance + changes |
| POST |
prepaid/top-up |
charge default payment method for credits |
| POST |
usage |
historical usage aggregated by fields (API twin of the console Usage Explorer: API key, model, request IP, cluster, token type) |
# Audit (/audit)
| Method |
Path |
Purpose |
| GET |
/audit/teams/{teamId}/events |
pageSize, pageToken, eventFilter.userId, eventFilter.query, eventFilter.eventId, eventTimeFrom/To (ISO 8601), orderBy TIME_ASCENDING|TIME_DESCENDING → events[{eventTime, eventId, description, user}], nextPageToken. Administrative events only (key creation, team changes, e.g. ListApiKeys); never request content. |
# 4. ACL model
api-key:endpoint:<name> and api-key:model:<name>, wildcards *. Documented endpoint names: chat (chat and vision models), image (image generation); the full list comes from GET /auth/teams/{teamId}/endpoints, model names from GET /auth/teams/{teamId}/models (also GET /v1/models on the inference side). Our key: api-key:model:*, api-key:endpoint:*.
# 5. What is console-only vs API
| Capability |
Console |
Management API |
Inference API |
| Create/list/update/rotate/delete API keys |
yes (API Keys page; disable key) |
yes |
read own key: GET /v1/api-key, GET /v1/me |
| Management keys |
create (Settings → Management Keys) |
validate only |
— |
| Teams: create, rename, members (Admin/Member roles), auto-join by email domain, delete |
yes |
— (team-level ops not exposed) |
— |
| Zero Data Retention toggle (team-wide) |
yes (Team Settings) |
— |
read: /v1/me.zdr_status, header x-zero-data-retention |
| Billing: prepaid credits (guest checkout, promo codes), auto top-up, invoiced limit, payment methods, invoices, tax info |
yes |
read/set most (no add/delete payment method) |
— |
| Usage explorer (group/filter by key, model, IP, cluster, token type) |
yes |
POST …/usage |
per-request usage.cost_in_usd_ticks |
| Audit log (search by event id / description / user, time filter) |
yes (admins) |
GET /audit/…/events |
— |
| Models & rate-limit tier view, limit-increase request |
yes (Models page) |
GET /auth/teams/{id}/models |
GET /v1/models (prices only) |
| Files & collections management, custom voices, tokenizer playground |
yes |
— |
Files/Collections/TTS APIs |
| mTLS enablement, monthly invoicing, Enterprise tiers |
support / sales |
— |
— |
# 6. Data handling facts (FAQ)
Default retention 30 days (encrypted, not used for training, then deleted). ZDR: team-wide, self-serve for admins where available; disables stateful Responses (store, previous_response_id), Files, Collections, Batch, deferred completions, stored image/video outputs (base64 only; own upload_url for video), per-key request logging, voice history. US regional endpoint keeps handling/inference/moderation/retained data in the US (not Files/Collections/tools). HIPAA via BAA questionnaire; GDPR/SOC 2 statements in FAQ; status page https://status.x.ai.