Authentification

Le contrat actuel de SMS v2

Cette page décrit l’authentification de l’API SMS sous /api/sms/v2/. Elle ne définit pas à l’avance le contrat des futurs produits. Pour l’ancienne API, consultez SMS v1 et la migration.

SMS v2 accepte uniquement une clé API organisationnelle émise dans BEFIANA Cloud. Transmettez la valeur complète, y compris son préfixe bf_sms_, dans l’en-tête suivant :

Authorization: Bearer bf_sms_<key_id>.<secret>

<key_id> et <secret> représentent les parties de la clé remise à sa création. Une clé historique, même rattachée à une organisation, un jeton JWT ou une clé transmise sans Bearer ne convient pas à v2. La connexion d’une personne à Cloud est distincte de l’authentification de votre intégration.

Pour les requêtes avec un corps JSON, utilisez Content-Type: application/json. Vous pouvez demander explicitement une réponse JSON avec Accept: application/json. Gardez la clé dans votre application serveur et transmettez les requêtes en HTTPS.

Une clé désigne une organisation

L’API déduit l’organisation de la clé. N’envoyez pas X-Organization : cet en-tête est refusé avec 400 invalid_organization_header. Pour travailler avec une autre organisation, utilisez une clé créée dans celle-ci.

Les ressources consultées sont limitées à cette organisation. Un identifiant de message ou de lot appartenant à une autre organisation renvoie 404 not_found. Posséder son identifiant ne donne pas accès à son contenu.

Les capacités autorisent les opérations

Une clé valide doit aussi posséder la capacité de l’opération demandée :

Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.

Capacité	Opérations SMS v2
sms.send	Créer un message immédiat avec POST /messages/.
sms.schedule	Créer un message avec send_at, ou un lot avec POST /message-batches/.
delivery.read	Consulter un message, un lot ou les messages d’un lot.
balance.read	Consulter les crédits avec GET /balance/.
contacts.manage	Créer ou mettre à jour un contact avec POST /contacts/.

Ces chemins sont relatifs à /api/sms/v2/. Une intégration d’envoi qui doit vérifier un résultat incertain a également besoin de delivery.read. L’autorisation d’administrer les clés dans Cloud est distincte des capacités accordées à une clé.

Diagnostiquer un refus d’accès

Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.

Code	Vérification
401 invalid_api_key	Vérifier la syntaxe Bearer, la valeur complète et l’état actif de la clé. Une clé révoquée ne permet plus d’authentifier une nouvelle requête.
403 insufficient_permissions	Utiliser une clé possédant la capacité nécessaire.
403 sms_unavailable	Vérifier dans Cloud que l’organisation et SMS sont actifs ; l’envoi exige aussi une activation SMS valide.

L’authentification ne remplace pas les autres contrôles : crédits disponibles, date de programmation et autorisation du nom d’expéditeur. Voir le catalogue des erreurs SMS.

Pour créer, conserver et renouveler vos identifiants, suivez le guide Clés API. La protection contre les doubles soumissions utilise un autre en-tête, Idempotency-Key, décrit dans Idempotence et reprises.