Authentification et clés

Chaque appel à l’API s’authentifie avec une clé, envoyée dans l’en-tête x-api-key. L’URL de base est https://api.qbill.dev/v1.

La clé dans l’en-tête

curl https://api.qbill.dev/v1/customers \
  -H "x-api-key: qb_test_sk_…"

Avec le SDK Node, la clé se passe au constructeur : new QBill("qb_test_sk_…"). Le paquet @qbill/node arrive bientôt sur npm ; en attendant, curl fonctionne dès aujourd’hui.

Trois sortes de clés

Préfixe Application Ce qu’elle peut faire
qb_test_sk_… sandbox Toute l’API, sans jamais atteindre Wave (voir Mode test).
qb_live_sk_… production Toute l’API, avec de vrais paiements.
qb_publishable_sk_… production ou sandbox Quatre routes en lecture : GET /v1/plans, GET /v1/plans/:id, GET /v1/plans/:id/tiers et GET /v1/plans/:id/price-components.

Une clé publishable qui appelle une autre route reçoit une erreur 403 publishable_key_forbidden. Elle ne peut donc pas créer de client, ni facturer, ni rembourser.

Lecture seule

Une clé peut être créée avec la portée read_only. Elle accepte les lectures et refuse toute écriture avec une erreur 403 api_key_read_only.

Une clé = une app

Une clé porte son application : il n’y a pas d’en-tête X-App-Id à envoyer. Une clé live ne peut être créée que sur l’application de production et une clé de test que sur la sandbox ; en créer une du mauvais côté est refusé avec une erreur 400 key_mode_mismatch. Une clé publishable peut être créée sur l’une ou l’autre.

Rotation

Créez, remplacez ou révoquez vos clés dans le portail développeur, sous Clés API. Deux règles :

  • le SDK refuse une clé publishable : elle ne sert qu’à lire les plans ;
  • ne mettez jamais une clé secrète (qb_test_sk_…, qb_live_sk_…) dans un navigateur ou une application mobile : gardez-la côté serveur.

Le format des erreurs est décrit dans Erreurs.

← Démarrage rapideMode test →