Apprendre

Authentification

Toute requête, à l’exception du document OpenAPI, est authentifiée par une clé API porteuse d’un ensemble fixe de portées.

Transmettre votre clé

Envoyez la clé sous forme de jeton bearer. C’est la forme autour de laquelle l’API est construite et celle que vous devriez utiliser.

Authorization: Bearer sk_live_a1b2c3d4.Xj9kQ2mZ7pR4tYv1WbN6cS0dF3gH8jK5lM2nP7qR4tY

Si une passerelle placée devant votre application supprime ou réécrit l’en-tête Authorization, SMSend accepte aussi la clé dans un en-tête dédié. Authorization est vérifié en premier.

X-API-Key: sk_live_a1b2c3d4.Xj9kQ2mZ7pR4tYv1WbN6cS0dF3gH8jK5lM2nP7qR4tY

Une clé n’est jamais acceptée dans une chaîne de requête, et ne le sera jamais. Les chaînes de requête sont écrites par défaut dans les journaux d’accès des serveurs web, ce qui déposerait un identifiant actif en clair sur disque et dans tous les agrégateurs de journaux en aval.

À quoi ressemble une clé

Une clé est un préfixe public et un secret, réunis par un point. Le préfixe indique quelle clé est utilisée ; le secret prouve que vous la détenez.

sk_live_a1b2c3d4.Xj9kQ2mZ7pR4tYv1WbN6cS0dF3gH8jK5lM2nP7qR4tY
└──── prefix ───┘ └────────────── secret ──────────────┘
  stored in clear     only a SHA-256 hash is stored

SMSend stocke le préfixe en clair et seulement une empreinte SHA-256 du secret. La valeur complète est affichée exactement une fois, à la création de la clé, et devient ensuite irrécupérable. Si vous la perdez, créez une nouvelle clé et révoquez l’ancienne.

Portées

Une clé porte un ensemble fixe de portées, choisi à sa création. Donnez à chaque intégration l’ensemble le plus étroit dont elle a besoin — une clé qui ne fait que lire des rapports ne devrait jamais pouvoir dépenser de l’argent.

Valeur	Signification
`MESSAGES_SEND`	Soumettre un lot. C’est la seule portée qui peut dépenser de l’argent.
`MESSAGES_READ`	Lire les lots, les messages individuels et le flux de rattrapage.
`ACCOUNT_READ`	Lire le solde du portefeuille, le plafond de crédit et le mode de facturation.
`SENDER_IDS_READ`	Lister les identifiants d’expéditeur enregistrés sur le compte.
`WEBHOOKS_MANAGE`	Créer, renouveler, activer et désactiver des points de terminaison webhook.

Les portées sont revérifiées à chaque requête

Les portées effectives d’une clé sont ses portées enregistrées, croisées avec ce que le membre qui l’a créée a le droit d’accorder aujourd’hui. Si cette personne est rétrogradée ou quitte l’équipe, la clé perd les portées correspondantes en l’espace d’une requête et se met à renvoyer INSUFFICIENT_SCOPE.

Quand l’authentification échoue

Tout échec d’authentification renvoie le même 401 avec le même message — une clé inconnue, un mauvais secret, une clé révoquée, une clé expirée et un compte suspendu sont indiscernables de l’extérieur. Laquelle de ces causes c’était n’apparaît que dans les journaux internes de SMSend. C’est délibéré : une erreur plus serviable confirmerait à un attaquant quelle moitié d’un identifiant deviné était la bonne.

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Provide a valid API key as `Authorization: Bearer <key>`.",
    "retryable": false,
    "detail": {},
    "request_id": "01K3F7XQZ8V2N4M6P8R0T5CJWE"
  }
}

Une clé valide à laquelle il manque la portée d’un point de terminaison donne un 403, pas un 401. L’identifiant est bon ; c’est la permission qui manque, et la réponse nomme la portée dont vous avez besoin.

403 Forbidden

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key does not carry the `SENDER_IDS_READ` scope.",
    "retryable": false,
    "detail": { "required_scope": "SENDER_IDS_READ" },
    "request_id": "01K3F7XQZ8V2N4M6P8R0T5CJWE"
  }
}

Renouveler une clé

Un compte peut détenir plusieurs clés actives à la fois, et c’est l’état pris en charge — c’est ce qui vous permet de renouveler sans fenêtre pendant laquelle plus rien ne fonctionne.

Créez une deuxième clé avec les mêmes portées.
Déployez-la, et vérifiez que le trafic passe bien par la nouvelle clé.
Révoquez la première clé. La révocation est un changement de statut, pas une suppression : la piste d’audit survit.

Si le membre qui a créé une clé quitte le compte, la clé n’est pas supprimée — ses portées effectives deviennent vides et chaque point de terminaison soumis à une portée se met à répondre INSUFFICIENT_SCOPE. Réémettez-la sous un membre actuel.