Permissions
Chaque route exige une permission ; un jeton ne porte que celles qu'on lui a accordées.
| Permission | Ce qu'elle ouvre | Apps tierces |
|---|---|---|
users:read | Voir les personnes de votre entreprise | immédiat |
users:write | Modifier les noms, postes et rôles des personnes | immédiat |
numbers:read | Voir vos numéros de téléphone | immédiat |
numbers:write | Attribuer vos numéros de téléphone | immédiat |
devices:read | Voir vos téléphones et applications | immédiat |
devices:write | Gérer vos téléphones et applications | immédiat |
calls:read | Consulter votre historique d'appels | immédiat |
calls:write | Passer des appels en votre nom | immédiat |
calls:control | Mettre en attente, transférer, enregistrer et raccrocher vos appels en cours | approbation requise |
recordings:read | Écouter vos enregistrements d'appels | approbation requise |
transcripts:read | Lire les transcriptions de vos appels | approbation requise |
presence:read | Voir qui est disponible | immédiat |
presence:write | Modifier votre statut et le mode ne pas déranger | immédiat |
messages:read | Lire vos messages texte | immédiat |
messages:write | Envoyer des messages texte en votre nom | immédiat |
voicemails:read | Écouter vos messages vocaux | immédiat |
voicemails:write | Marquer et supprimer vos messages vocaux | immédiat |
faxes:read | Voir vos télécopies | immédiat |
faxes:write | Envoyer des télécopies en votre nom | immédiat |
webhooks:manage | Être averti des appels et des messages | immédiat |
account:read | Voir le nom et le forfait de votre entreprise | immédiat |
Les permissions approbation requise touchent à ce qu'une personne dit au téléphone : contrôler un appel en cours, écouter un enregistrement, lire une transcription. Une clé API de votre propre entreprise les reçoit à la création ; une app OAuth utilisée dans une autre entreprise que celle qui l'a enregistrée doit d'abord les demander (Développeur → Apps → Demander) et être approuvée par AIMERICA. Tant qu'elle ne l'est pas, /oauth/authorize refuse ces permissions avec error=invalid_scope.
Une route nomme sa permission dans la référence (x-scope). Une requête sans elle répond 403 insufficient_scope :
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="calls:read"
{"error": {"type": "insufficient_scope", "message": "This token does not have the calls:read scope", "request_id": "…"}}Les clés créées avant le 25 septembre 2026 gardent leurs anciens noms (calls:read, calls:write, messages:read, messages:write, numbers:read, contacts:read, contacts:write) ; les cinq premiers sont acceptés tels quels par l'API v1, les contacts restent sur l'ancienne API de l'application.