Multiple client keys: spending limits, IP allowlists and expiry

A YesCaptcha account can have up to 20 clientKeys (including the original one), managed on the Keys & security page of the yescaptcha.com dashboard. Every clientKey can create tasks and check the balance, and they all draw on the same account balance. Each one can have its own spending limit, IP allowlist and expiry, and changes take effect within a few seconds.

Typical uses: separate keys for testing and production, or for different projects; giving keys to your own downstream customers or partners, each with its own limit; and if one clientKey leaks, you delete just that one without touching your other programs.

Primary key and sub-keys

	Primary key	Sub-key
What it is	Your original clientKey; one per account	Any key created in addition to the primary key; up to 19
Spending limit, IP allowlist, expiry	Can be set	Can be set
Reset	Yes: the old one stops working at once and the balance moves to the new one	No; delete it and create another
Delete	No	Yes: stops working within seconds and cannot be restored

• They all have the same format: the first 40 characters are the secret, followed by your user ID.
• Resetting the primary key does not affect sub-keys.
• Whichever clientKey you use to create tasks or check the balance, the API and its responses are the same; the only difference is the extra checks for the spending limit, IP allowlist and expiry.

Create a client key

1. Sign in at yescaptcha.com and open the Keys & security page (yescaptcha.com/security).
2. Under “All keys”, click “New sub-key”. Name (up to 40 characters), spending limit, IP allowlist and expiry are all optional and can be changed later.
3. Verify your identity again when prompted. Creating, changing and deleting keys all require this.
4. Copy the full clientKey and put it in your program. You can view it again later with the eye icon in the list.

Note

Creating, changing and deleting keys take effect within a few seconds. A call made right after creating a key may return ERROR_KEY_DOES_NOT_EXIST; wait a few seconds and try again. For a few seconds after you delete a key or tighten its settings, requests already on their way may still be handled under the old settings.

Spending limit

A spending limit caps how many points a clientKey can spend in one period (1,000 points = ¥1). It can be anywhere from 1 to 10,000,000,000 points. There are four periods, reset on Beijing time (UTC+8):

Period	Resets
Per day	Every day at 00:00
Per week	Every Monday at 00:00
Per month	On the 1st of every month at 00:00
One-time total	Never. Once it is used up, this clientKey can no longer create tasks; raise the limit to keep using it

• It counts the points actually charged: points refunded for failed or timed-out tasks go back to the limit as well.
• If what is left of the limit for the current period is less than the cost of a task, createTask returns ERROR_KEY_QUOTA_EXCEEDED. It is not charged and does not count towards automatic pauses.
• The list in the dashboard shows how much each clientKey has used in the current period and when it resets next.
• A spending limit is not a separate balance: all clientKeys draw on the same account balance, and when the account balance runs out you get ERROR_ZERO_BALANCE as usual.

When you call getBalance with a clientKey that has a spending limit, balance is the smaller of the account balance and what is left of the limit for the current period, and there is an extra field keyQuotaRemaining (remaining limit, in points). A clientKey without a limit does not get this field, and the response is the same as before.

{
  "errorId": 0,
  "balance": 20000,
  "softBalance": 0,
  "inviteBalance": 0,
  "inviteBy": 0,
  "keyQuotaRemaining": 20000
}

IP allowlist

A clientKey with an IP allowlist only works for requests sent from the IP addresses on the list. Leave it empty for no restriction.

• Enter the public IP of the machine calling the YesCaptcha API (its outgoing IP), not the proxy in the task parameters. If several machines call the API, add the public IP of each one.
• One IPv4 or IPv6 address or CIDR range per line, up to 50 entries. A single address allows just that IP.
• Write ranges as the network address: 203.0.113.0/24 is accepted, 203.0.113.5/24 is not (the host bits are not zero).

203.0.113.10
198.51.100.0/24
2001:db8::/32

• If the request comes from an IP that is not on the list, createTask and getBalance return ERROR_KEY_IP_NOT_ALLOWED. It is not charged and does not count towards automatic pauses.
• If your outgoing IP changes (home broadband, cloud functions, rotating egress), don’t set an allowlist, or allow the whole range.

Expiry

• Any clientKey, including the primary key, can have an expiry time within the next ten years. You can change or remove it at any time.
• After it expires, createTask and getBalance with that key return ERROR_KEY_EXPIRED and are not charged. Tasks that were already created can still be collected with getTaskResult.
• If a clientKey goes unused for a long time, the system sets an expiry time on it to protect your account and sends you an email before it expires. That expiry time cannot be changed: generate a new primary key (the balance moves to it automatically) or create another clientKey, then update your program.

Balance, concurrency limit and automatic pauses

• Balance: all clientKeys draw on the same account balance. Top-ups, VIP top-up bonuses, referral rewards and developer revenue share all belong to the account, whichever clientKey you use.
• Concurrency limit: counted per account; all your clientKeys share the same limit. See Rate limits.
• Automatic pauses: counted per clientKey. If one clientKey is paused for too many errors, the others are not affected.

Related error codes

Error code	When it is returned
ERROR_KEY_QUOTA_EXCEEDED	What is left of the limit for the current period is less than the cost of this task (createTask)
ERROR_KEY_IP_NOT_ALLOWED	The request IP is not on this clientKey’s IP allowlist (createTask, getBalance)
ERROR_KEY_EXPIRED	The clientKey has expired (createTask, getBalance)

None of these is charged. See Error codes for what to do.