HonkIOPour commencer
Authentification et clés API
Chaque requête porte une clé API. Les clés de test font les mêmes vérifications que les clés réelles sans rien envoyer ni facturer, et les permissions de chaque clé limitent ce qu’elle peut atteindre.
Authentification
Toutes les requêtes API nécessitent un jeton Bearer dans l'en-tête Authorization. Utilisez test keys (mk_test_...) pour le développement : aucun vrai SMS n'est envoyé, aucuns frais. Utilisez live keys (mk_live_...) pour la production.
Mode test
Une clé de test (mk_test_...) fonctionne dès la création de votre compte, avant toute recharge. Un nouveau compte démarre en PENDING_PAYMENT : une clé de production reçoit 402 PAYMENT_REQUIRED pour tout, sauf quelques lectures de démarrage (GET /v1/accounts/me, GET /v1/accounts/:id, GET /v1/accounts/:id/topup-allowance et GET /v1/pricing) ; les clés de test passent quand même.
Un envoi de test applique les mêmes vérifications qu’un envoi réel : consentement et désabonnement LCAP, les listes d’autorisation et de blocage de la clé API, les vérifications de central réservé et de numéro injoignable, et la vérification de destination canadienne. Il ne vérifie pas la propriété du numéro from, la vérification du propriétaire, votre solde, les limites d’envoi, ni la vérification LNNTE (non appliquée à aucun envoi pour l’instant). Aucun message n’atteint un opérateur : il est tarifé exactement comme un envoi réel, pour que vous voyiez le coût réel, puis la ligne est marquée comme livrée.
Une clé de test est un bac à sable sans portée réelle : elle ne peut pas acheter ni libérer de numéros de téléphone, créer, renouveler ou révoquer des clés de production, envoyer le code de vérification du propriétaire, lancer un effacement, modifier les webhooks, déposer une demande de volume ou d’allocation de numéros, ni modifier les listes ou le refus par défaut d’une clé de production, et elle ne peut pas lire la file des lettres mortes. L’historique des messages et des vérifications via une clé de test ne montre que des lignes de test. Les contacts, groupes, listes, consentements et désabonnements restent modifiables, sauf ceux que la liste d’autorisation ou de refus d’une clé de production référence : les modifier exige aussi une clé de production.
Clés API et permissions
Chaque clé API porte un objet de permissions, une chaîne de lettres par ressource : r (lecture, GET), w (écriture, POST), m (modification, PATCH ou PUT), d (suppression, DELETE). Une ressource absente ou une chaîne vide signifie aucun accès à celle-ci. Vous pouvez aussi transmettre la clé dans un en-tête X-API-Key plutôt qu’un jeton Bearer dans Authorization. Quelques routes exigent une lettre moins évidente : POST /v1/compliance/erasure exige compliance:d ; POST /v1/accounts/:id/phone-verification et son /confirm exigent account:m ; POST /v1/compliance/dncl/check exige compliance:r ; DELETE /v1/contact-groups/:id/members/:contactId exige contact_groups:m ; et DELETE /v1/accounts/:id/api-keys/:keyId/lists/:mode exige api_keys:m.
Les ressources qu’un objet de permissions peut nommer :
| Ressource | Signification |
|---|---|
| messages | Envoyer et lire les messages SMS |
| phone_numbers | Provisionner, rechercher et libérer des numéros de téléphone |
| contacts | Gérer les contacts |
| contact_groups | Gérer les groupes de contacts et les diffusions |
| lists | Gérer les listes de contacts d’autorisation et de blocage |
| compliance | Consentements LCAP, désinscriptions et vérifications LNNTE |
| webhooks | Gérer les points de terminaison webhook |
| verify | Envoyer des NPU et vérifier les codes |
| account | Consulter ou modifier le profil du compte et son utilisation |
| api_keys | Gérer les clés API |
| emails | Envoyer et lire des courriels |
| email_domains | Gérer les domaines courriel |
| email_suppressions | Gérer les listes de suppression courriel |
| email_templates | Gérer les modèles de courriel enregistrés |
Une nouvelle clé hérite par défaut des permissions de la clé qui l’a créée : omettez permissions et elle obtient exactement ce que l’appelant possède. En demander davantage nécessite une confirmation par mot de passe (un en-tête X-Step-Up-Token avec la portée api_keys:elevate), sinon la requête est refusée avec 403 PERMISSION_ESCALATION. Une clé de test ne peut créer que des clés de test.