Aller au contenu
Wajub
Chargement des API keys…

Authentification

Authentification par clé : trois types de clés, permissions par scopes, listes d'IP autorisées.

Wajub vous authentifie avec une API key envoyée telle quelle dans l'en-tête Authorization. Pas de préfixe Bearer, pas de parcours OAuth, pas d'étape de signature.

En-têtes de requête
Authorization: sk_test.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i...
Content-Type: application/json

Anatomie d'une clé

Une clé se compose d'un préfixe, d'un point, puis de 96 caractères aléatoires. Le préfixe est la partie qui vous renseigne :

Format de clé
sk_test . kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i...
└──┬──┘   └──────────────────┬──────────────────┘
 │                         └─ 96 random characters, shown once at creation
 └─ type (sk/pk/rk) and environment (_test or nothing)

Le préfixe porte deux informations à la fois : le type de la clé et son environnement.

PréfixeTypeEnvironnement
pk.PubliqueLive
pk_test.PubliqueSandbox
sk.PrivéeLive
sk_test.PrivéeSandbox
rk.RestreinteLive
rk_test.RestreinteSandbox

C'est la clé qui choisit l'environnement, pas l'URL

https://api.wajub.com sert les deux environnements. Une clé _test est aiguillée vers la base de données de la sandbox avant toute requête en base, si bien que le même code atteint les données de test ou les données live uniquement selon la clé que vous chargez. Changer d'environnement revient à changer de secret, jamais d'endpoint.

Les trois types de clés

Privée (sk.) donne accès à toutes les opérations et ne doit jamais quitter votre serveur. Publique (pk.) peut être embarquée sans risque dans un navigateur ou une application mobile, et elle est refusée sur tout endpoint qui déplace ou révèle de l'argent. Restreinte (rk.) est une clé privée limitée à une liste explicite de scopes, destinée à un tiers ou à une seule intégration.

Types de clés acceptés par chaque endpoint :

EndpointsPublique pk.Privée sk.Restreinte rk.
GET /, /providers, /channels, /countries, /currenciesOuiOuiOui
/payments, /customers, /links, /invoices, /accountsOuiOuiAvec le scope
/balance, /transfers, /refunds, /beneficiaries, /disputes, /webhooks, /events, /identityNonOuiAvec le scope
/taxNonOuiAvec le scope
/shieldNonOuiNon

Une clé publique envoyée sur une ligne marquée Non est rejetée avant toute autre vérification :

Réponse · 406 Not Acceptable
{
"code": 406,
"status": "Not Acceptable",
"message": "Private Key Required"
}

Scopes des clés restreintes

Une clé restreinte porte une liste de scopes au format resource.action. La ressource vient du premier segment du chemin, l'action de la méthode HTTP : GET, HEAD et OPTIONS correspondent à read, tout le reste à write. Un GET /transfers exige donc transfer.read, et un POST /transfers exige transfer.write.

Paire de scopesDonne accès à
payment.read / payment.write/payments et /providers
customer.read / customer.write/customers
transfer.read / transfer.write/transfers
refund.read / refund.write/refunds
recipient.read / recipient.write/beneficiaries
invoice.read / invoice.write/invoices
dispute.read / dispute.write/disputes
webhook.read / webhook.write/webhooks
event.read / event.write/events, y compris le renvoi d'une livraison
link.read / link.write/links
identity.read / identity.write/identity
tax.read / tax.write/tax
balance.read/balance, aucun endpoint d'écriture n'existe
account.read/accounts, en lecture seule

Deux scopes de la liste n'ont pas d'équivalent en écriture. balance.read est en lecture seule parce que le solde n'a aucun endpoint d'écriture. /accounts est un cas différent : créer, modifier ou supprimer un sous-compte est une écriture, et aucun scope account.write n'existe encore, donc ces trois appels exigent une clé privée. Il en va de même pour /shield, qui n'a aucun scope et n'accepte donc que les clés privées. settings.read et settings.write apparaissent dans le Dashboard, mais aucun endpoint ne les utilise aujourd'hui.

Cinq chemins ignorent complètement les scopes, car ils renvoient les mêmes données pour toutes les clés de la plateforme : GET /, /channels, /countries, /currencies, ainsi que DELETE /keys/current, pour qu'une clé générée par wajub login puisse toujours se révoquer elle-même.

Un scope que vous n'avez pas accordé renvoie un 403 qui nomme exactement ce qui manquait :

Réponse · 403 Forbidden
{
"code": 403,
"status": "Forbidden",
"message": "This API key does not have permission to write transfer"
}

Restreindre davantage une clé

Deux contraintes facultatives s'appliquent à tous les types de clés. Vous les définissez à la création de la clé dans Settings → Developer → API Keys.

allowed_ipsarrayfacultatif
Adresses IPv4/IPv6 exactes ou plages CIDR. Une requête venant d'ailleurs est refusée avec 403 IP address not allowed for this API key, quel que soit le type de clé.
expires_attimestampfacultatif
Passé cette date, la clé répond 401 Invalid or revoked API credentials. Laissez vide pour une clé sans date de fin.

Authentifier une requête

Le même appel dans les cinq stacks prises en charge. GET /balance exige une clé privée, ce qui en fait un bon moyen de vérifier que votre identifiant côté serveur est bien chargé :

curl https://api.wajub.com/balance \
-H "Authorization: $WAJUB_API_KEY"

Ou envoyez-la directement depuis cette page. Renseignez d'abord vos clés dans la barre supérieure :

Erreurs d'authentification

Quatre échecs différents, tous identifiables grâce au message :

CodemessageCe qui s'est passé
401Invalid API credentialsAucune clé, ou aucune équipe ne lui correspond.
401Invalid or revoked API credentialsLa clé a existé mais elle est inactive, supprimée ou expirée.
403IP address not allowed for this API keyLa clé a une liste d'IP autorisées et vous n'en faites pas partie.
406Private Key RequiredUne clé publique sur un endpoint réservé aux clés privées.
Réponse · 401 Unauthorized
{
"code": 401,
"status": "Unauthorized",
"message": "Invalid API credentials"
}

Les clés privées sont bloquées dans le navigateur

Toute requête qui porte une clé sk. ou sk_test. et un en-tête Origin ou Referer est refusée. Ces en-têtes sont ajoutés par les navigateurs, pas par les serveurs : leur présence à côté d'une clé privée signifie que le secret a atteint le front-end.

Réponse · 403 Forbidden
{
"code": 403,
"status": "Forbidden",
"message": "Security Alert: You are trying to use a Private Key from a browser/frontend. Private keys must ONLY be used in server-side code. Please use a Public Key for frontend requests.",
"documentation_url": "https://docs.wajub.com/api/authentication#private-keys-are-blocked-in-the-browser"
}

La première fois que ce blocage se déclenche pour une clé donnée, le propriétaire de l'équipe et les administrateurs reçoivent un e-mail, au maximum un par clé et par heure. Si vous le rencontrez sans vous y attendre, cherchez une clé privée embarquée dans du code front-end, puis déplacez l'appel vers votre serveur ou passez à une clé publique.

Bonnes habitudes

  • Gardez vos clés dans des variables d'environnement, jamais dans le dépôt ni dans un bundle front-end.
  • Utilisez une clé distincte par service, pas une seule clé partagée par toute votre infrastructure. Une limite de 100 requêtes par minute s'applique par clé : séparer vos clés vous donne donc aussi plus de débit.
  • Donnez aux tiers une clé restreinte avec les deux ou trois scopes dont ils ont réellement besoin.
  • Définissez expires_at sur tout ce qui est temporaire : un script de migration, l'accès d'une agence, un prototype.
  • Renouvelez vos clés après le départ d'un membre de l'équipe.

Pages associées

Que pensez-vous de ce contenu ?