# Multiple client keys: spending limits, IP allowlists and expiry

> A YesCaptcha account can have up to 20 client keys, all drawing on the same account balance. Each one can have its own spending limit (per day, week or month, or a one-time total, reset on Beijing time), IP allowlist and expiry, taking effect within seconds.

Source: https://docs.yescaptcha.com/en/account/client-keys/ · Last verified: 2026-10-29

A YesCaptcha account can have up to 20 `clientKey`s (including the original one), managed on the Keys & security page of the [yescaptcha.com](https://yescaptcha.com/security) 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](https://yescaptcha.com/) and open the Keys & security page ([yescaptcha.com/security](https://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`](https://docs.yescaptcha.com/en/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED). It is not charged and does not count towards [automatic pauses](https://docs.yescaptcha.com/en/api/rate-limits.md).
-   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 `clientKey`s draw on the same account balance, and when the account balance runs out you get `ERROR_ZERO_BALANCE` as usual.

When you call [`getBalance`](https://docs.yescaptcha.com/en/api/get-balance.md) 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.

```json
{
  "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).

```text
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`](https://docs.yescaptcha.com/en/api/errors.md#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`](https://docs.yescaptcha.com/en/api/errors.md#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 `clientKey`s 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 `clientKey`s share the same limit. See [Rate limits](https://docs.yescaptcha.com/en/api/rate-limits.md).
-   **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`](https://docs.yescaptcha.com/en/api/errors.md#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`](https://docs.yescaptcha.com/en/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | The request IP is not on this `clientKey`’s IP allowlist (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/en/api/errors.md#ERROR_KEY_EXPIRED) | The `clientKey` has expired (`createTask`, `getBalance`) |

None of these is charged. See [Error codes](https://docs.yescaptcha.com/en/api/errors.md) for what to do.