> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waspytech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes y permisos

> Qué scopes existen, qué endpoints protegen y cómo configurarlos.

## 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](/limitations)) | —                                                                                                                                                                       |
| `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` |

<Note>
  **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**.
</Note>

***

## 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`:

```json theme={null}
{
  "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.