- Documentation
- API · Version 1.0
- Scopes
Scopes
On this page
An API client can only call the routes whose scope it holds. Each route declares the one it requires; a client that lacks it receives 403.
What each scope opens
| Scope | Routes |
|---|---|
| (none) | 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 |
There is no separate deletion scope for media: adding a file to your own library and removing it are the same decision. Likewise, reading your webhook endpoints and registering one both fall under webhooks:manage.
Request as few scopes as possible. An integration that only publishes needs destinations:read, publications:create and, if it attaches images, media:create.
Missing scope: 403
{
"error": {
"code": "insufficient_scope",
"message": "This client does not hold the « publications:cancel » scope.",
"required_ability": "publications:cancel"
}
}
error.required_ability is the exact name of the scope to have granted. The message only repeats it.
A client's brand
A client is attached to a workspace, and optionally to one brand of that workspace.
- Attached to a brand, it sees only that brand: its destinations, its publications, its media. It does not need to send
brand_id, and cannot designate another brand, even one in its workspace; the value sent is ignored. - Attached to the workspace only, it sees all the brands of the workspace. Writes that create a resource attached to a brand —
POST /publicationsandPOST /media— then requirebrand_id.GET /brandsgives the available identifiers.
Without brand_id, a workspace client receives:
{
"error": {
"code": "brand_required",
"message": "This client covers several brands: send « brand_id »."
}
}
With a brand_id that designates no brand of the workspace — a typo, a deleted brand or a brand from another workspace — it receives brand_not_found:
{
"error": {
"code": "brand_not_found",
"message": "This brand does not belong to your workspace."
}
}
Both respond 422.
Out of scope: 404
A resource that belongs to another brand or another workspace responds 404, exactly like a made-up identifier. Every request starts from the brands the client can see, never from the identifier supplied: the foreign resource does not exist within the request. Responding 403 would confirm its existence.
The two cases therefore read as follows:
403 insufficient_scope: your client is not allowed to call this route;404 not_found: this resource does not exist for your client.