Scopes y permisos

Scopes disponibles

Cada API key puede tener uno o más scopes que limitan qué operaciones puede hacer. Si no asignás scopes al crear la key, tiene acceso completo.

Scope	Descripción	Endpoints
`account:read`	Leer información de la cuenta	`GET /account`
`channels:read`	Listar canales (números) conectados	`GET /channels`
`contacts:read`	Leer contactos	`GET /contacts`, `GET /contacts/:id`
`contacts:write`	Crear y actualizar contactos	`POST /contacts`, `PATCH /contacts/:id`
`conversations:read`	Leer conversaciones y sus mensajes	`GET /conversations`, `GET /conversations/:id`, `GET /conversations/:id/messages`
`conversations:write`	Actualizar conversación, mark-as-read, typing	`PATCH /conversations/:id`, `POST /conversations/:id/read`, `POST /conversations/:id/typing`, `POST /messages/:waMessageId/read`
`messages:read`	Leer mensajes individuales	`GET /messages/:id`
`messages:write`	Enviar mensajes	`POST /messages`
`templates:read`	Listar y consultar templates	`GET /templates`, `GET /templates/:id`, `GET /templates/by-name/:name`
`media:read`	Resolver media a signed URLs	`GET /media/:id`, `GET /media/by-key`
`media:write`	Subir media (no expuesto todavía — ver Limitaciones)	—
`webhooks:read`	Leer suscripciones y deliveries	`GET /webhooks`, `GET /webhooks/:id`, `GET /webhooks/:id/deliveries`
`webhooks:write`	Crear/modificar suscripciones, rotate-secret, test, replay	`POST /webhooks`, `PATCH /webhooks/:id`, `DELETE /webhooks/:id`, `POST /webhooks/:id/test`, `POST /webhooks/:id/replay/:deliveryId`, `POST /webhooks/:id/rotate-secret`

Superposición conversations:read ↔ messages:read: GET /conversations/:id/messages requiere conversations:read (porque listás los mensajes “de una conversación”), mientras que GET /messages/:id requiere messages:read (porque accedés a un mensaje “individual”). Para keys de solo lectura, lo común es asignar ambos.

Cómo funcionan

Una key sin scopes puede hacer todo (acceso completo).
Una key con scopes solo puede acceder a los endpoints correspondientes.
Si una key intenta acceder a un endpoint sin el scope necesario, recibe un 403:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Esta API key no tiene permiso para esta operación.",
    "status": 403
  },
  "meta": { "requestId": "..." }
}

Ejemplos de uso

Key de solo lectura

Para un dashboard que solo consulta datos:

Scopes: account:read, contacts:read, conversations:read, templates:read

Key para enviar mensajes

Para un sistema que envía notificaciones:

Scopes: messages:write, contacts:read, templates:read

Key de gestión de contactos

Para un CRM que sincroniza contactos:

Scopes: contacts:read, contacts:write

Relación con el plan

Los scopes limitan qué puede hacer una API key, pero los límites del plan aplican a toda la cuenta. Si tu plan tiene un límite de 1.000 conversaciones/mes, ese límite se aplica sin importar los scopes de la key.

Empezar

Fundamentos

Conceptos

Webhooks

Otros

Scopes y permisos

Scopes disponibles

Cómo funcionan

Ejemplos de uso

Key de solo lectura

Key para enviar mensajes

Key de gestión de contactos

Relación con el plan

​Scopes disponibles

​Cómo funcionan

​Ejemplos de uso

​Key de solo lectura

​Key para enviar mensajes

​Key de gestión de contactos

​Relación con el plan

Scopes disponibles

Cómo funcionan

Ejemplos de uso

Key de solo lectura

Key para enviar mensajes

Key de gestión de contactos

Relación con el plan