# Keys and authentication

> Noptcha API keys (nop_live_ and nop_test_), where to send them, scopes and restrictions.

Source: https://noptcha.com/docs/authentication/

Every request is authenticated with an API key of your organization.

## Key format

| Prefix | Kind |
| --- | --- |
| `nop_live_` | Live key: real solving, charged to your balance |
| `nop_test_` | Test key: runs in the [sandbox](https://noptcha.com/docs/sandbox.md), never charged |

After the prefix come 36 random characters and a 4-character checksum (letters and digits). The prefix lets secret scanners recognise leaked keys; the checksum lets us reject mistyped keys at once.

A key is shown **once**, when you create it in the console. We store only a hash; the console shows the prefix and the last four characters. If you lose a key, revoke it and create a new one.

## Where the key goes

| API | How |
| --- | --- |
| Native API (v1) | `Authorization: Bearer nop_live_…` header |
| Compatibility API | `clientKey` field in the JSON body |
| 2captcha legacy API | `key` parameter; prefer POST, see [below](#keep-keys-out-of-urls) |

The key is checked before anything else in the request, so an invalid key is reported even when other fields are wrong.

## Scopes

| Scope | Allows |
| --- | --- |
| `tasks:write` | creating tasks, reading their results, reporting answers |
| `balance:read` | `GET /v1/balance`, `getBalance` |
| `usage:read` | `GET /v1/usage` |

`GET /v1/me` and `GET /v1/types` work with any valid key. A missing scope is `403 forbidden` in v1 and `ERROR_KEY_DOES_NOT_EXIST` in the compatibility API.

## Restrictions

A key can be limited to:

-   **task types**: only the listed types can be created (`403 forbidden` / `ERROR_TASK_NOT_SUPPORTED` otherwise);
-   **client IP ranges** (CIDR): requests from other addresses get `403 forbidden` / `ERROR_IP_NOT_ALLOWED`;
-   **a budget per period**: when it is used up, task creation fails with `402 budget_exceeded` / `ERROR_ZERO_BALANCE`;
-   **an expiry date**: 7 days before it, a [`key.expiring` webhook](https://noptcha.com/docs/webhooks.md#account-events) and an email to owners and admins warn you.

`GET /v1/me` shows the restrictions, the budget and how much of it is used, and the rate limits of the key.

## Invalid keys and IP blocking

After 50 requests with invalid keys from one IP address within 10 minutes (an IPv6 /64 counts as one address; an IPv6 /48 is blocked after 500), that address is blocked for the rest of the 10 minutes for keys we do not already know: v1 answers `429 rate_limited`, the compatibility API `ERROR_IP_BLOCKED`. Valid keys keep working from that address.

## Keep keys out of URLs

Send keys in headers or request bodies. The 2captcha legacy protocol allows the key in the query string; URLs end up in proxy logs, security tools and browser history, so use POST with a form or JSON body there too. If a key leaks, revoke it in the console and create a new one.