- Documentation
- API · Version 1.0
- Périmètres
Périmètres
Sur cette page
Un client d'API ne peut appeler que les routes dont il possède le périmètre. Chaque route déclare celui qu'elle exige ; un client qui ne l'a pas reçoit 403.
Ce que chaque périmètre ouvre
| Périmètre | Routes |
|---|---|
| (aucun) | GET /me |
brands:read |
GET /brands |
destinations:read |
GET /destinations, GET /destinations/{id} |
publications:read |
GET /publications, GET /publications/{id} |
publications:create |
POST /publications |
publications:update |
POST /publications/{id}/publish |
publications:cancel |
POST /publications/{id}/cancel |
publications:retry |
POST /publications/{id}/retry |
media:create |
POST /media, DELETE /media/{id} |
media:read |
GET /media, GET /media/{id} |
webhooks:manage |
GET /webhooks, POST /webhooks, PATCH /webhooks/{id}, DELETE /webhooks/{id}, POST /webhooks/{id}/test |
Il n'existe pas de périmètre de suppression distinct pour les médias : déposer et retirer un fichier de sa propre bibliothèque relèvent de la même décision. De même, lire ses endpoints de webhook et en déclarer un relèvent tous deux de webhooks:manage.
Demandez le moins de périmètres possible. Une intégration qui se contente de publier a besoin de destinations:read, publications:create et, si elle joint des images, media:create.
Périmètre manquant : 403
{
"error": {
"code": "insufficient_scope",
"message": "This client does not hold the « publications:cancel » scope.",
"required_ability": "publications:cancel"
}
}
error.required_ability est le nom exact du périmètre à faire accorder. Le message ne fait que le répéter.
La marque d'un client
Un client est rattaché à un espace de travail, et éventuellement à une marque de cet espace.
- Rattaché à une marque, il ne voit que cette marque : ses destinations, ses publications, ses médias. Il n'a pas à envoyer
brand_id, et ne peut pas en désigner une autre, même de son espace ; la valeur envoyée est ignorée. - Rattaché à l'espace seul, il voit toutes les marques de l'espace. Les écritures qui créent une ressource rattachée à une marque —
POST /publicationsetPOST /media— exigent alorsbrand_id.GET /brandsdonne les identifiants disponibles.
Sans brand_id, un client d'espace reçoit :
{
"error": {
"code": "brand_required",
"message": "This client covers several brands: send « brand_id »."
}
}
Avec un brand_id qui ne désigne aucune marque de l'espace — faute de frappe, marque supprimée ou marque d'un autre espace — il reçoit brand_not_found :
{
"error": {
"code": "brand_not_found",
"message": "This brand does not belong to your workspace."
}
}
Les deux répondent 422.
Hors périmètre : 404
Une ressource qui appartient à une autre marque ou à un autre espace de travail répond 404, exactement comme un identifiant inventé. Chaque requête part des marques que le client peut voir, jamais de l'identifiant fourni : la ressource étrangère n'existe pas dans la requête. Répondre 403 confirmerait son existence.
Les deux cas se lisent donc ainsi :
403 insufficient_scope: votre client n'a pas le droit d'appeler cette route ;404 not_found: cette ressource n'existe pas pour votre client.