# Plusieurs ClientKey : limites, liste blanche d'IP et expiration

> Un compte YesCaptcha peut avoir jusqu'à 20 ClientKey, qui débitent toutes le même solde. Chacune peut avoir sa propre limite de dépenses (par jour, par semaine, par mois ou en total unique, remise à zéro à l'heure de Pékin), sa liste blanche d'IP et son expiration, appliquées en quelques secondes.

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

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/client-keys/

Un compte YesCaptcha peut avoir jusqu’à 20 `clientKey` (y compris la première), gérées dans la page « Clés et sécurité » du tableau de bord [yescaptcha.com](https://yescaptcha.com/security). Chaque `clientKey` peut créer des tâches et consulter le solde, et toutes débitent le même solde du compte. Chacune peut avoir sa propre limite de dépenses, sa liste blanche d’IP et son expiration, appliquées en quelques secondes.

Cas d’usage typiques : séparer les environnements de test et de production, ou les différents projets ; confier une clé à vos clients ou partenaires, chacun avec sa propre limite ; et si une `clientKey` fuit, ne supprimer que celle-ci sans toucher aux autres programmes.

## Clé principale et sous-clés

|  | Clé principale | Sous-clé |
| --- | --- | --- |
| Définition | La `clientKey` d’origine, une par compte | Toute clé créée en plus de la clé principale, 19 au maximum |
| Limite, liste blanche d’IP, expiration | Possible | Possible |
| Réinitialisation | Oui : l’ancienne cesse de fonctionner immédiatement et le solde passe à la nouvelle | Non ; supprimez-la et créez-en une autre |
| Suppression | Non | Oui : cesse de fonctionner en quelques secondes, irréversible |

-   Toutes ont le même format : les 40 premiers caractères forment le secret, suivis de votre ID utilisateur.
-   Réinitialiser la clé principale n’affecte pas les sous-clés.
-   Quelle que soit la `clientKey` utilisée pour créer des tâches ou consulter le solde, l’API et ses réponses sont identiques ; seules s’ajoutent les vérifications de limite, de liste blanche d’IP et d’expiration.

## Créer une clé

1.  Connectez-vous sur [yescaptcha.com](https://yescaptcha.com/) et ouvrez la page « Clés et sécurité » ([yescaptcha.com/security](https://yescaptcha.com/security)).
2.  Dans « Toutes les clés », cliquez sur « Nouvelle sous-clé ». Le nom (40 caractères maximum), la limite, la liste blanche d’IP et l’expiration sont facultatifs et modifiables plus tard.
3.  Confirmez de nouveau votre identité lorsque c’est demandé. La création, la modification et la suppression l’exigent toutes.
4.  Copiez la `clientKey` complète et configurez-la dans votre programme. Vous pourrez la consulter de nouveau plus tard avec l’icône en forme d’œil dans la liste.

> **Note:** La création, la modification et la suppression sont appliquées en quelques secondes. Un appel effectué juste après la création peut renvoyer `ERROR_KEY_DOES_NOT_EXIST` ; attendez quelques secondes et réessayez. Pendant quelques secondes après une suppression ou un durcissement des réglages, les requêtes déjà en cours peuvent encore être traitées avec les anciens réglages.

## Limite de dépenses

La limite plafonne le nombre de points qu’une `clientKey` peut dépenser sur une période (1,000 points = ¥1), de 1 à 10,000,000,000 points. Il existe quatre périodes, remises à zéro à l’heure de Pékin (UTC+8) :

| Période | Remise à zéro |
| --- | --- |
| Par jour | Chaque jour à 00:00 |
| Par semaine | Chaque lundi à 00:00 |
| Par mois | Le 1er de chaque mois à 00:00 |
| Total unique | Jamais. Une fois épuisée, cette `clientKey` ne peut plus créer de tâches ; augmentez la limite pour continuer à l’utiliser |

-   Le calcul porte sur les points réellement débités : les points remboursés pour les tâches échouées ou expirées sont aussi rendus à la limite.
-   Si le reste de la limite de la période en cours est inférieur au coût de la tâche, `createTask` renvoie [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/fr/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED). Aucun point n’est débité et l’erreur ne compte pas pour la [suspension automatique](https://docs.yescaptcha.com/fr/api/rate-limits.md).
-   La liste du tableau de bord indique, pour chaque `clientKey`, ce qui a été utilisé sur la période en cours et la prochaine remise à zéro.
-   La limite n’est pas un solde distinct : toutes les `clientKey` débitent le même solde du compte, et quand le solde du compte est épuisé, vous obtenez `ERROR_ZERO_BALANCE` comme d’habitude.

Si vous appelez [`getBalance`](https://docs.yescaptcha.com/fr/api/get-balance.md) avec une `clientKey` qui a une limite, `balance` est la plus petite valeur entre le solde du compte et le reste de la limite de la période en cours, et un champ supplémentaire `keyQuotaRemaining` (limite restante, en points) est renvoyé. Une `clientKey` sans limite n’a pas ce champ et la réponse reste identique à avant.

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

## Liste blanche d’IP

Une `clientKey` avec une liste blanche d’IP ne fonctionne que pour les requêtes envoyées depuis les adresses IP de la liste. Laissez-la vide pour ne mettre aucune restriction.

-   Saisissez l’**IP publique de la machine qui appelle l’API YesCaptcha** (son IP de sortie), et non le proxy indiqué dans les paramètres de la tâche. Si plusieurs machines appellent l’API, ajoutez l’IP publique de chacune.
-   Une adresse IPv4 ou IPv6, ou une plage CIDR, par ligne, 50 entrées au maximum. Une adresse seule n’autorise que cette IP.
-   Écrivez les plages avec l’adresse réseau : `203.0.113.0/24` est accepté, `203.0.113.5/24` ne l’est pas (les bits d’hôte ne sont pas à 0).

```text
203.0.113.10
198.51.100.0/24
2001:db8::/32
```

-   Si la requête provient d’une IP absente de la liste, `createTask` et `getBalance` renvoient [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/fr/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED). Aucun point n’est débité et l’erreur ne compte pas pour la suspension automatique.
-   Si votre IP de sortie change (box domestique, fonctions cloud, sorties en rotation), ne définissez pas de liste blanche, ou autorisez toute la plage.

## Expiration

-   Toute `clientKey`, clé principale comprise, peut avoir une date d’expiration dans les dix ans à venir. Vous pouvez la modifier ou la retirer à tout moment.
-   Après l’expiration, `createTask` et `getBalance` avec cette clé renvoient [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/fr/api/errors.md#ERROR_KEY_EXPIRED) et aucun point n’est débité. Les tâches déjà créées peuvent toujours être récupérées avec `getTaskResult`.
-   Si une `clientKey` reste inutilisée pendant longtemps, le système lui attribue une date d’expiration pour protéger votre compte et vous envoie un e-mail avant l’échéance. Cette date ne peut pas être modifiée : générez une nouvelle clé principale (le solde y est transféré automatiquement) ou créez une autre `clientKey`, puis mettez à jour votre programme.

## Solde, limite de tâches simultanées et suspension automatique

-   **Solde** : toutes les `clientKey` débitent le même solde du compte. Les recharges, les bonus VIP, les récompenses de parrainage et la part développeur sont rattachés au compte, quelle que soit la `clientKey` utilisée.
-   **Limite de tâches simultanées** : calculée par compte ; toutes vos `clientKey` partagent la même limite. Voir [Limite de tâches simultanées et suspension automatique](https://docs.yescaptcha.com/fr/api/rate-limits.md).
-   **Suspension automatique** : calculée par `clientKey`. Si une `clientKey` est suspendue pour trop d’erreurs, les autres ne sont pas affectées.

## Codes d’erreur associés

| Code d’erreur | Quand il est renvoyé |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/fr/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | Le reste de la limite de la période en cours est inférieur au coût de cette tâche (`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/fr/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | L’IP de la requête n’est pas dans la liste blanche d’IP de cette `clientKey` (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/fr/api/errors.md#ERROR_KEY_EXPIRED) | La `clientKey` a expiré (`createTask`, `getBalance`) |

Aucun de ces codes ne débite de points. Voir [Codes d’erreur](https://docs.yescaptcha.com/fr/api/errors.md) pour savoir quoi faire.