# xAI Management API (https://management-api.x.ai) and account endpoints

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