Skip to content
Quiet Social

Scopes

This documentation is translated from French. Should the two versions differ, the French version prevails.

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 /publications and POST /media — then require brand_id. GET /brands gives 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.