Keys and authentication
Every request is authenticated with an API key of your organization.
Key format
Section titled “Key format”| Prefix | Kind |
|---|---|
nop_live_ |
Live key: real solving, charged to your balance |
nop_test_ |
Test key: runs in the sandbox, 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
Section titled “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 |
The key is checked before anything else in the request, so an invalid key is reported even when other fields are wrong.
Scopes
Section titled “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
Section titled “Restrictions”A key can be limited to:
- task types: only the listed types can be created (
403 forbidden/ERROR_TASK_NOT_SUPPORTEDotherwise); - 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.expiringwebhook 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
Section titled “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
Section titled “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.