> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tawked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, their modes and scopes, and the hardening options.

Every request carries an API key. Send it as a Bearer token, or in the `x-api-key` header for clients that cannot set `Authorization`:

```bash theme={null}
curl https://tawked.com/v1/verify/b7e5c2b0-9c1a-4e2f-8f2a-3a6b0e9d1c44 \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxx"
```

Keys are created in the dashboard under **Applications, then your application, then Keys**, and shown once. Store them in your secret manager, never in client-side code.

## Key modes

The prefix tells you the mode; the API enforces it.

| Prefix        | Mode    | What it can do                                                                                                                                                                     |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tk_live_`    | Live    | Production sends. Needs an approved application.                                                                                                                                   |
| `tk_test_`    | Sandbox | Everything a live key does, with the [sandbox limits](/sandbox). Issued before approval.                                                                                           |
| `tk_partner_` | Partner | Account-level key for platforms that provision applications for their merchants. Pass `application` in the body (or `?application=` on a GET) to say which application is sending. |

A live key on a sandbox-only account, or a revoked key, answers `401 unauthorized`. A key that belongs to an application that is not approved yet answers `403 account_not_active`.

## Scopes

A key is `full` (the default) or `check`. A check-scoped key may only call `check` and `GET /v1/verify/{id}`; `start`, `resend` and `cancel` answer `403 insufficient_scope`. Use it on a server that only ever confirms codes and never sends them. Partner keys are always full scope.

## Expiry and IP allowlists

Set at creation time, checked right after the key is recognised and before anything else:

* **Expiry**: once `expires_at` passes, every call answers `401 key_expired`.
* **IP allowlist**: exact IPs and CIDR ranges, IPv4 and IPv6. A caller outside the list gets `403 ip_not_allowed`. Empty means every address.

<Tip>
  Rotate keys by creating the new one first, deploying it, then revoking the old one. There is no window where both must be in the same request.
</Tip>

## The order of checks

Knowing the order helps you read an error. On every endpoint:

1. Per-key rate limit (`429 too_many_requests`), checked before authentication.
2. Key recognised, then expiry, IP allowlist and scope.
3. Account and application state (`403 account_not_active`).
4. Request shape (`400 invalid_json`, `400 invalid_request`), channel and destination (`422`).
5. Sandbox gates, hourly caps and the protection guard (`429`, `403`).
6. Balance (`402 insufficient_credits`).
7. The send itself (`502 send_failed`, refunded).

The [Errors](/errors) page lists every code.