Getting started

Authentication

One key per account, sent either in the request body or as a bearer token. Keys are stored as hashes and shown exactly once.

Sending your key#

The conventional form in this category is a clientKey field in the JSON body, and that is supported so existing integrations work unchanged:

JSON

{
  "clientKey": "void_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "task": { "type": "ReCaptchaV3", "...": "..." }
}

A standard bearer header works too, and is preferable if your logging pipeline already knows to redact Authorization:

cURL

curl -X POST https://api.voidcaptcha.com/v1/getResult \
  -H "Authorization: Bearer void_a1b2c3d4e5f60718293a4b5c6d7e8f90" \
  -H "Content-Type: application/json" \
  -d '{ "task": { "type": "ReCaptchaV3", "...": "..." } }'

If both are present the header wins. Sending neither returns ERROR_KEY_MISSING.

Live and test keys#

Every key has the same shape — void_ followed by 32 hex characters — whether it is live or test. A live key charges your balance. A test key solves a synthetic challenge, returns a well-formed response in about two seconds and never charges anything.

Warning

Because the two are indistinguishable by sight, a test key pasted into production config fails quietly rather than loudly: calls succeed, tokens come back, and the target rejects every one. The dashboard labels which is which — check there, not the string.

Test keys exist so your integration tests can exercise the real code path — the same endpoint, the same envelope, the same parsing — without spending money or depending on a third-party site being up. Run them in CI on every commit.

Note

A test key will not solve a real challenge. It returns a syntactically valid token that the target will reject. Use it to prove your plumbing works, not your end-to-end flow.

Rotating a key#

Rotating issues a new key and revokes the previous one immediately. There is no grace period, so deploy the new key first if you cannot tolerate failed calls, or create a second key, migrate, then revoke the old one.

Rotate from your dashboard. Calls made with a revoked key return ERROR_KEY_INVALID.

Looking after your key#

Treat it as a bearer credential

Anyone holding the key can spend your balance. Keep it in an environment variable or a secrets manager, never in source control, and never in client-side code — a key shipped to a browser is a key published.

We store only a SHA-256 hash, so we cannot show you a key again or recover a lost one. If a key may have leaked, rotate it — that is the entire remedy and it takes a second.

Last updated on 2 August 2026