Aller au contenu
Quiet Social

Périmètres

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 /publications et POST /media — exigent alors brand_id. GET /brands donne 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.