Authentification

Chaque appel à l’API 221 Pay porte une clé API d’un projet. La clé identifie le projet et son mode ; 221 Pay crée le compte marchand du projet au premier appel authentifié.

Clés de test et clés liveCopier le lien de la section

Les clés déjà émises en 221pay_test_, 221pay_live_ ou sk_221_ restent valides jusqu’à leur expiration ou révocation.

Une clé se compose du préfixe, de 43 caractères base62 et d’une somme de contrôle de 6 caractères (CRC32). Une clé mal formée est refusée avant toute recherche. Expression pour détecter une clé dans un dépôt de code ou des journaux :

\b(?:sk_221_pay_|221pay_)(test|live)_[0-9A-Za-z]{43}[0-9A-Za-z]{6}\b

Créer une cléCopier le lien de la section

Tableau de bord 221 Pay, Développeurs > Clés API (administrateur du projet) :

Un projet compte au plus 5 clés actives.

Envoyer la cléCopier le lien de la section

Authorization: Bearer sk_221_pay_test_…

curl "$API_URL/v1/balances" -H "Authorization: Bearer $API_KEY"

La clé reste côté serveur : jamais dans un navigateur, jamais dans une application mobile publiée.

PortéesCopier le lien de la section

Une clé sans la portée payments reçoit 403 MISSING_SCOPE sur les routes 221 Pay. Une clé dédiée à 221 Pay, avec la seule portée payments, limite l’effet d’une fuite. Les routes webhook du projet acceptent toute clé du projet, quelle que soit sa portée.

Quota quotidienCopier le lien de la section

Les routes 221 Pay n’ont pas de quota quotidien : seule la limite de 600 requêtes par minute et par projet s’applique (Erreurs). Le quota quotidien ne concerne que les routes de données (portée data).

Chaque clé porte un daily_limit, le nombre d’appels de données qu’elle peut faire par jour. Il se fixe à la création par l’API (POST /v1/projets/{id}/cles, entier d’au moins 1) et ne peut pas dépasser la limite par défaut d’une clé, qui s’applique aussi quand il est omis. Le compte a sa propre limite, partagée par toutes ses clés et tous ses projets. Valeurs par défaut du serveur : 1 000 appels par clé et par compte ; 5 000 par clé et 10 000 par compte quand l’identité est vérifiée, et une clé d’un compte vérifié compte au moins 5 000. Le compteur repart à zéro à minuit UTC.

Développeurs > Utilisation affiche les valeurs en vigueur et la consommation du jour. Les propriétaires du projet reçoivent un e-mail à 80 % puis à 100 % du quota d’une clé.

Au-delà, l’appel reçoit 429 QUOTA_EXCEEDED avec Retry-After (secondes jusqu’à minuit UTC) :

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 5000
RateLimit-Remaining: 0
Retry-After: 21887

{"code": "QUOTA_EXCEEDED", "message": "Quota quotidien du compte ou de la clé atteint.", "request_id": "2f6c9a0e-5b1d-4e7f-8c3a-9d0b1e2f3a4c", "limit": 5000, "reset_at": "2026-10-08T00:00:00.000Z"}

Voir aussi Authentification et clé.

Rôle d’une cléCopier le lien de la section

Une clé agit avec le rôle administrateur sur son projet : elle crée des paiements, des liens, des remboursements et des retraits. L’administrateur qui l’a créée répond de son usage. Les rôles des personnes du projet sont décrits dans Tableau de bord.

Identifiant du projetCopier le lien de la section

$PROJECT_ID est l’identifiant du projet dans les routes /v1/projets/{id}/…. Une clé le lit elle-même, quelle que soit sa portée :

curl "$API_URL/v1/moi/cle" -H "Authorization: Bearer $API_KEY"

{ "project_id": "…", "mode": "test", "scopes": ["payments", "data"], "name": "Serveur boutique" }

project_id est la valeur de $PROJECT_ID. Cette route exige une clé : la session du tableau de bord reçoit 401.

Le tableau de bord l’affiche aussi, dans l’identifiant marchand, de la forme p221_<identifiant du projet> : Accueil > Développeurs > Identifiants, ligne « Identifiant marchand » (bouton de copie). Retirer le préfixe p221_. Ce bloc de l’Accueil apparaît dès qu’une clé API active existe.

Ne pas confondre avec le champ « Identifiant » de Mon compte > Compte, carte « Projet » : c’est le nom court (slug) du projet, que l’API refuse (404) à la place de l’identifiant. Avec la session du tableau de bord, GET /v1/projets renvoie aussi l’id de chaque projet.

RotationCopier le lien de la section

La rotation remplace une clé par une nouvelle, de même nom, mode, portées et quota. L’ancienne reste valide pendant le délai choisi, le temps de déployer la nouvelle : now (révoquée tout de suite), 1h, 24h ou 7d.

Tableau de bord, Développeurs > Clés API, ou avec la session du tableau de bord :

curl -X POST "$API_URL/v1/projets/$PROJECT_ID/cles/$KEY_ID/rotate" \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"grace": "24h"}'

La réponse contient le nouveau secret, affiché une seule fois, et rotated_from, l’identifiant de la clé remplacée.

Passer en mode liveCopier le lien de la section

Un administrateur du projet active le mode live, avec une confirmation explicite : les clés live déplacent de l’argent réel.

curl -X PUT "$API_URL/v1/projets/$PROJECT_ID/live" \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"live_enabled": true, "acknowledged": true}'

Le changement est journalisé. Les clés live se créent ensuite dans Développeurs > Clés API. GET /v1/projets/{id}/live renvoie live_enabled.

Mode du serveur : gateway_modeCopier le lien de la section

curl -s "$API_URL/v1/balances" -H "Authorization: Bearer $API_KEY" | jq -r .gateway_mode
curl -s "$API_URL/health" | jq -r .payments.gateway_mode

Le parcours de test est décrit dans Tests.

Erreurs d’authentificationCopier le lien de la section

Une clé peut être révoquée à tout moment par un administrateur du projet, ou désactivée par 221 en cas d’usage abusif.