Authentification

L’API REST de SIP Caller authentifie les requêtes à l’aide de clés API. Chaque clé API possède un jeton secret, que votre application envoie dans l’en-tête Authorization de chaque requête.

Créer une clé API

Les clés API sont créées depuis la Console Web, dans Paramètres > Clés API, par un utilisateur ayant le rôle Administrateur. Lors de la création de la clé, vous choisissez :

• Un nom, pour identifier l’application qui l’utilise.
• Une date d’expiration. Après cette date, la clé cesse de fonctionner. L’expiration ne peut pas être prolongée ultérieurement.
• Les rôles accordés à la clé, qui définissent ce que l’application peut faire. Les rôles ne peuvent pas être modifiés ultérieurement.

Lorsque la clé est créée, SIP Caller affiche son jeton une seule fois. Copiez-le et conservez-le dans un endroit sûr, comme un gestionnaire de secrets. SIP Caller ne stocke pas le jeton, il ne peut donc pas être récupéré : si vous le perdez, créez une nouvelle clé API.

Consultez Clés API pour un guide pas à pas.

Authentifier les requêtes

Envoyez le jeton en tant que jeton Bearer dans l’en-tête Authorization :

Chaque requête doit être authentifiée. Gardez à l’esprit que :

• Une clé API appartient à un seul compte : l’ACCOUNT_ID de l’URL doit donc être celui du compte dans lequel la clé a été créée.
• Les requêtes doivent être effectuées en HTTPS.
• Le jeton est un secret, et donne accès à votre compte. Ne l’incluez pas dans du code côté client, comme des pages web ou des applications mobiles, et ne le versionnez pas dans des dépôts de code source.

Rôles

Chaque point de terminaison exige que la clé API dispose d’au moins un des rôles suivants :

Rôle	Permet
Administrateur des campagnes	Accès complet aux campagnes, aux numéros de campagne, aux listes noires, aux listes de contacts et aux rapports de campagne.
Lecteur des campagnes	Accès en lecture seule aux campagnes, aux numéros de campagne, aux listes noires, aux listes de contacts et aux rapports de campagne.
Administrateur des numéros de campagne	Lire, ajouter et supprimer les numéros des campagnes. Peut être limité à des campagnes spécifiques.
Fournisseur de numéros de campagne	Ajouter des numéros aux campagnes, sans pouvoir les lire ni les supprimer. Peut être limité à des campagnes spécifiques.

Accordez à chaque application uniquement les rôles dont elle a besoin. Par exemple, un formulaire web qui envoie de nouveaux prospects vers une campagne n’a besoin que du rôle Fournisseur de numéros de campagne, limité à cette campagne.

Erreurs d’authentification

Statut	Quand
401 Unauthorized	L’en-tête Authorization est absent, ou le jeton est mal formé, invalide ou expiré.
403 Forbidden	Le jeton est valide, mais la clé API a été supprimée, appartient à un autre compte, ou ne dispose pas d’un rôle autorisant l’opération.

Consultez Erreurs pour le format des réponses d’erreur.

Révoquer une clé API

Pour révoquer l’accès d’une application, supprimez sa clé API depuis Paramètres > Clés API. Les requêtes effectuées avec le jeton d’une clé supprimée échouent immédiatement avec 403 Forbidden.

Nous vous recommandons de renouveler régulièrement vos clés : créez une nouvelle clé, mettez à jour votre application pour qu’elle l’utilise, puis supprimez l’ancienne.