# Authentication

Every call carries one header, Authorization: Bearer with your key. An account holds up to 50 keys, each with its own spending limit, expiry and scope.

## The header

The credential goes in `Authorization: Bearer`. It is an API key, or the sign-in token the Console uses. It is not accepted in the address or in any other header.

```bash
curl "https://api.dataxapi.com/v1/account" \
  -H "Authorization: Bearer $DATAXAPI_API_KEY"
```

Keep the key in the environment variable `DATAXAPI_API_KEY`: the SDKs, the command line and the MCP entries all read it from there.

## Keys

A key is `dx_` followed by 32 characters. It is shown **once**, when it is created, and cannot be read back later: the service keeps only its first characters, to tell keys apart. A lost key is replaced by a new one. An account holds up to 50 keys; make and manage them on the [Keys page](https://dataxapi.com/console/keys/) of the Console.

| Each key has | What it does |
| --- | --- |
| Name | What you call it. |
| Spending limit | By day, by month or in total, in US dollars. Days and months are UTC. A call the limit does not cover is refused before it runs. |
| Expiry | After it the key answers 401. |
| Scope | A list of endpoints the key may call; none means all. An endpoint added to the service later is not in an existing list. |
| Disable, enable | Switch a key off and on again. |
| Revoke | For good: a revoked key cannot be brought back. |

> A key holds no money. All keys of an account draw on one balance and share one rate limit.

## What a key may do

`GET /v1/account` answers for the key that asks. It is free.

- `balance`: What the account can spend now, in US dollars.
- `key.budget`: `daily`, `monthly` and `total`, each with `limit`, `spent` and `remaining`.
- `key.scopes`: The endpoints this key may call; `null` means all.
- `key.expires_at`: When the key expires; `null` means never.
- `rate`: The rate limit in force for the account: see [Rate limits](https://dataxapi.com/docs/rate-limits/).

The same from the SDKs is `dx.account()`, and from the command line `dataxapi balance`.

## Without a key

The catalog needs no key: what there is, what each endpoint takes and returns, and every price.

- `GET /v1/catalog`: The whole catalog.
- `GET /v1/catalog/capabilities/{id}`: One endpoint's whole contract, and whether it is up now.
- `GET /v1/catalog/search`: Finds the endpoint for a need put in words, in English or Chinese: `query`, `platform`, `category`.
- `GET /v1/catalog/status`: What is up now: the data of the [status page](https://dataxapi.com/status/).

```bash
curl -G "https://api.dataxapi.com/v1/catalog/search" --data-urlencode "query=tiktok video search"
```

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| [`unauthorized`](https://dataxapi.com/docs/errors/#unauthorized) | 401 | No credential was sent, or it is invalid, disabled or expired | Check the header and the key's state on the Keys page. |
| [`key_scope_denied`](https://dataxapi.com/docs/errors/#key_scope_denied) | 403 | This key may not call this endpoint | Add the endpoint to the key's scope, or use another key. |
| [`key_budget_exceeded`](https://dataxapi.com/docs/errors/#key_budget_exceeded) | 402 | This key's spending limit does not cover the call | Raise the limit, or wait for the day or the month to turn (`reason` says which limit). |

None of these is charged.

---

Catalog revision c48ce454ae6c4c65. [HTML version](https://dataxapi.com/docs/authentication/)