- Documentación
- API · Versión 1.0
- Permisos
Permisos
En esta página
Un cliente de API solo puede llamar a las rutas cuyo permiso posee. Cada ruta declara el que exige; un cliente que no lo tiene recibe 403.
Lo que abre cada permiso
| Permiso | Rutas |
|---|---|
| (ninguno) | 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 |
No existe un permiso de eliminación distinto para los medios: depositar y retirar un archivo de la propia biblioteca forman parte de la misma decisión. Del mismo modo, leer tus endpoints de webhook y declarar uno dependen ambos de webhooks:manage.
Solicita el menor número posible de permisos. Una integración que se limita a publicar necesita destinations:read, publications:create y, si adjunta imágenes, media:create.
Permiso que falta: 403
{
"error": {
"code": "insufficient_scope",
"message": "This client does not hold the « publications:cancel » scope.",
"required_ability": "publications:cancel"
}
}
error.required_ability es el nombre exacto del permiso que hay que hacer conceder. El mensaje no hace más que repetirlo.
La marca de un cliente
Un cliente está vinculado a un espacio de trabajo y, opcionalmente, a una marca de ese espacio.
- Vinculado a una marca, solo ve esa marca: sus destinos, sus publicaciones, sus medios. No tiene que enviar
brand_id, y no puede designar otra, ni siquiera de su espacio; el valor enviado se ignora. - Vinculado solo al espacio, ve todas las marcas del espacio. Las escrituras que crean un recurso vinculado a una marca —
POST /publicationsyPOST /media— exigen entoncesbrand_id.GET /brandsda los identificadores disponibles.
Sin brand_id, un cliente de espacio recibe:
{
"error": {
"code": "brand_required",
"message": "This client covers several brands: send « brand_id »."
}
}
Con un brand_id que no designa ninguna marca del espacio — errata, marca eliminada o marca de otro espacio — recibe brand_not_found:
{
"error": {
"code": "brand_not_found",
"message": "This brand does not belong to your workspace."
}
}
Ambos responden 422.
Fuera de alcance: 404
Un recurso que pertenece a otra marca o a otro espacio de trabajo responde 404, exactamente igual que un identificador inventado. Cada petición parte de las marcas que el cliente puede ver, nunca del identificador proporcionado: el recurso ajeno no existe en la petición. Responder 403 confirmaría su existencia.
Los dos casos se leen, por tanto, así:
403 insufficient_scope: tu cliente no tiene derecho a llamar a esta ruta;404 not_found: este recurso no existe para tu cliente.