# Authentication and API keys

> How to send your BigModel.io API key, which headers are accepted, how key groups, quotas, expiry and IP rules work, and how to fix 401 and 403 errors.

Web version: https://bigmodel.io/docs/authentication · Updated 2026-10-18

Every request to BigModel.io is authenticated with an API key from the console. Send it in a header; the gateway checks it before routing the request to a model.

| Header | Example | Used by |
|---|---|---|
| `Authorization` | `Bearer sk-...` | OpenAI SDKs, most tools, `ANTHROPIC_AUTH_TOKEN` in Claude Code |
| `x-api-key` | `sk-...` | Anthropic SDKs and clients |
| `x-goog-api-key` | `sk-...` | Gemini-style clients |

If several are present, `Authorization` wins, then `x-api-key`, then `x-goog-api-key`. The `Bearer` scheme is case-insensitive.

## Create a key

1. Sign in and open [API Keys](https://bigmodel.io/keys).
2. Click create, enter a name and choose a **group**. The group decides which models and endpoints the key can call and its rate multiplier.
3. Optionally set a quota, spend windows, expiry and IP rules (see below).
4. Copy the key and store it as an environment variable.

```bash
export BIGMODEL_API_KEY="sk-..."
```

Keys look like `sk-` followed by 64 hex characters. You can also enter a custom key of at least 16 characters using letters, digits, `_` and `-`.

The key is not shown only once. The table shows a masked form (first 6 and last 4 characters), and the copy button copies the full key at any time. Anyone with the key can spend your balance, so keep it server-side and out of repositories and browser code.

## Send the key

```bash [cURL]
curl https://bigmodel.io/v1/chat/completions \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"glm-5.3","messages":[{"role":"user","content":"ping"}]}'
```

```python [Python]
import os
from openai import OpenAI

client = OpenAI(base_url="https://bigmodel.io/v1", api_key=os.environ["BIGMODEL_API_KEY"])
```

```js [Node.js]
import Anthropic from "@anthropic-ai/sdk";

// The Anthropic SDK sends x-api-key; the root URL has no /v1.
const client = new Anthropic({ baseURL: "https://bigmodel.io", apiKey: process.env.BIGMODEL_API_KEY });
```

Do not put the key in the URL. `?key=` or `?api_key=` is rejected with 400 `api_key_in_query_deprecated`.

## Groups

A key belongs to exactly one group, and you choose it when you create the key. The group sets:

- **Models.** Only models the group serves can be called. There is no per-key model allow-list.
- **Endpoints.** GLM and DeepSeek groups serve only `/v1/chat/completions`; `/v1/messages`, `/v1/messages/count_tokens` and `/v1/responses` return 404 for them. Anthropic groups serve `/v1/messages` natively and convert Chat Completions. OpenAI groups serve Chat Completions and Responses, and convert `/v1/messages` if the group allows it.
- **Price multiplier.** Charges are the model price times the group's multiplier. A personal rate can replace it.

A key with no group returns 403 `permission_error` "API Key is not assigned to any group". Edit the key and choose a group.

## Per-key settings

Each key can be edited in [API Keys](https://bigmodel.io/keys):

| Setting | Effect | Error when hit |
|---|---|---|
| Status | Disable or enable the key | 401 `API_KEY_DISABLED` |
| Quota (USD) | Total spend cap, 0 = unlimited; used quota can be reset | 429 `API_KEY_QUOTA_EXHAUSTED` |
| Spend windows (USD) | Caps per 5 hours, 1 day and 7 days, 0 = unlimited | 429 `rate_limit_exceeded` |
| Expiry | 7, 30, 90 days or a custom date | 403 `API_KEY_EXPIRED` |
| IP whitelist / blacklist | IPs or CIDRs, one per line | 403 `ACCESS_DENIED` |

The `ACCESS_DENIED` message is deliberately vague; if you set IP rules, check them first. Use separate keys per app or environment so you can cap, rotate or disable one without touching the others. Details: [Per-key limits & budgets](https://bigmodel.io/docs/key-limits).

## Verify the setup

`GET /v1/usage` checks the key without spending anything and works even when the key is expired or exhausted:

```bash
curl https://bigmodel.io/v1/usage \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"
```

`isValid`, `status`, the quota or balance, and `expires_at` tell you whether the key will be accepted. The **Test key** action in API Keys runs a test request from the console.

## Troubleshooting

**401 `API_KEY_REQUIRED`.** No key reached the gateway. Check the header name, and that the environment variable is set in the process that sends the request.

**401 `INVALID_API_KEY`.** The key is wrong or deleted. Copy it again from [API Keys](https://bigmodel.io/keys); watch for stray spaces or quotes.

**401 `USER_NOT_FOUND` or `USER_INACTIVE`.** The account that owns the key is missing or not active. Contact [Support](https://bigmodel.io/support).

**403 `ACCESS_DENIED`.** The request IP is blocked by the key's IP whitelist or blacklist.

**403 `permission_error` "not assigned to any group".** Assign a group to the key.

**404 `... platform only supports /v1/chat/completions`.** The key's group is Chat Completions only. Use a key from another group for Messages or Responses clients.

**403 `INSUFFICIENT_BALANCE`.** Authentication succeeded, but the balance is zero or below. See [Billing & top-ups](https://bigmodel.io/docs/billing).

## Related

- [Errors](https://bigmodel.io/docs/errors)
- [Limits & rate limits](https://bigmodel.io/docs/rate-limits)
- [Per-key limits & budgets](https://bigmodel.io/docs/key-limits)
- [API quickstart](https://bigmodel.io/docs/quickstart)