# Autenticación y permisos

> Claves API, los 20 scopes y qué desbloquea cada uno, rotación de claves, límites de peticiones por plan y aislamiento de espacios en la API de WhatSetter.

Source: https://docs.whatsetter.com/es/developers/authentication/

Cada petición a la API y cada sesión MCP se autentica con una clave API. Esta página explica qué es una clave, qué puede hacer y qué límites se le aplican.

## Claves API

- Formato: `ws_live_` seguido de 40 caracteres hexadecimales.
- Una clave pertenece al **espacio de trabajo**, no a una persona. Se crea en **Configuración**, luego **API y MCP**, por un propietario o un admin.
- Se muestra **una sola vez**, justo después de crearla. WhatSetter solo guarda una huella, así que nadie puede volver a leerla.
- Puedes revocarla en cualquier momento con **Revocar**, luego **Revocar para siempre**. El dashboard confirma: **Clave revocada. Efectivo en menos de un minuto.** Revocarla corta la API REST y el [servidor MCP](/es/developers/mcp/) a la vez.

## Enviar la clave

Pasa la clave como Bearer token. La cabecera `X-Api-Key` también se acepta.

```bash
curl https://app.whatsetter.com/api/v1/me \
  -H "Authorization: Bearer ws_live_…"
```

Sin clave recibes `401 missing_api_key`. Con una clave desconocida o revocada recibes `401 invalid_api_key`.

## Scopes

Al crear una clave eliges sus **Permisos**: **Acceso completo** (todos los scopes, incluido el envío de mensajes y el cambio de prompts) o **Personalizado** (eliges exactamente qué puede hacer esta clave). Una clave sin el scope correcto recibe `403 insufficient_scope`, y el mensaje nombra el scope que falta.

| Scope | Qué desbloquea | Endpoints |
|---|---|---|
| `leads:read` | Leer leads y sus notas | `GET /leads`, `GET /leads/{id}`, `GET /leads/{id}/notes` |
| `leads:write` | Cambiar estado, etiquetas, responsable, siguiente acción y resultado del deal; pasar una conversación a un humano y devolverla; añadir notas | `PATCH /leads/{id}`, `POST /leads/{id}/handoff`, `POST /leads/{id}/resume`, `POST /leads/{id}/notes` |
| `conversations:read` | Bandeja de entrada e historial completo de mensajes | `GET /conversations`, `GET /conversations/{leadId}/messages` |
| `lists:read` | Listar tus listas de contactos | `GET /lists` |
| `lists:write` | Crear listas e importar contactos | `POST /lists`, `POST /lists/{id}/leads` |
| `campaigns:read` | Listar campañas | `GET /campaigns` |
| `campaigns:write` | Pausar y reanudar campañas | `POST /campaigns/{id}/pause`, `POST /campaigns/{id}/resume` |
| `messages:send` | Enviar un mensaje a un lead que ya está en conversación, en WhatsApp, Instagram o Messenger; añadir un lead opt-in a una campaña (esto envía su primer mensaje) | `POST /messages`, `POST /campaigns/{id}/leads` |
| `bookings:read` | Reuniones agendadas por el agente | `GET /bookings` |
| `groups:read` | Grupos de WhatsApp rastreados: detalle, miembros, mensajes, entradas y salidas | `GET /groups`, `GET /groups/{id}`, `GET /groups/{id}/members`, `GET /groups/{id}/messages`, `GET /groups/{id}/events` |
| `webhooks:manage` | Crear, listar, probar y borrar suscripciones de webhook | `GET /webhooks`, `POST /webhooks`, `DELETE /webhooks/{id}`, `POST /webhooks/{id}/test` |
| `blocklist:manage` | Leer, añadir y quitar números y prefijos bloqueados | `GET /blocked-contacts`, `POST /blocked-contacts`, `DELETE /blocked-contacts/{id}` |
| `team:read` | Listar los miembros del espacio (id, nombre, rol), para asignar leads | `GET /team/members` |
| `links:read` | Leer los enlaces rastreados y sus estadísticas de clics | `GET /links`, `GET /links/{id}` |
| `prompts:read` | Leer los prompts con los que trabaja un agente y sus versiones | `GET /campaigns/{id}/prompts`, `GET /campaigns/{id}/prompts/{type}`, `GET /campaigns/{id}/prompts/{type}/versions`, `GET /campaigns/{id}/prompts/{type}/versions/{versionId}` |
| `prompts:write` | Cambiar un prompt o restaurar una versión. El cambio está en línea al instante | `PUT /campaigns/{id}/prompts/{type}`, `POST /campaigns/{id}/prompts/{type}/versions/{versionId}/restore` |
| `knowledge:read` | Leer las bases de conocimientos y sus respuestas, y buscar en ellas como lo hace el agente | `GET /knowledge-bases`, `GET /knowledge-bases/{id}`, `GET /knowledge-bases/{id}/search`, `GET /knowledge-bases/{id}/answers` |
| `knowledge:write` | Añadir, corregir y quitar respuestas | `POST /knowledge-bases/{id}/answers`, `PATCH /knowledge-bases/{id}/answers/{answerId}`, `DELETE /knowledge-bases/{id}/answers/{answerId}` |
| `instagram:read` | Leer las cuentas de Instagram, las publicaciones programadas, las cifras y los mejores momentos de las publicaciones, las automatizaciones y sus cifras | `GET /instagram/accounts`, `GET /instagram/posts`, `GET /instagram/posts/{id}`, `GET /instagram/insights/posts`, `GET /instagram/insights/best-times`, `GET /instagram/automations`, `GET /instagram/stats` |
| `instagram:write` | Programar, cambiar y cancelar publicaciones (se publican públicamente); crear, cambiar, encender y borrar automatizaciones (una encendida escribe a personas reales) | `POST /instagram/posts`, `PATCH /instagram/posts/{id}`, `DELETE /instagram/posts/{id}`, `POST /instagram/automations`, `PATCH /instagram/automations/{id}`, `DELETE /instagram/automations/{id}` |

`GET /me` no necesita ningún scope: cualquier clave válida puede llamarlo.

> **Seis scopes son nuevos**
`prompts:read`, `prompts:write`, `knowledge:read` y `knowledge:write` llegaron con los endpoints de prompts y de bases de conocimientos. Una clave creada antes no los lleva, ni siquiera una de **Acceso completo**: crea una clave nueva si necesitas esos endpoints. Lo mismo vale para `blocklist:manage`, `team:read` y `links:read`, que llegaron antes. Mira las guías de [prompts de los agentes](/es/developers/guides/prompts/) y [bases de conocimientos](/es/developers/guides/knowledge/).

> **Instagram necesita una clave reciente**
`instagram:read` e `instagram:write` llegaron con los endpoints de Instagram. Una clave de **Acceso completo** es la lista de scopes que existían el día en que se creó: una clave anterior a estos endpoints no los lleva, y las rutas de Instagram le responden `403 insufficient_scope`. Crea una clave nueva. Los mensajes privados de Instagram y Messenger no necesitan ningún scope de Instagram: se leen con `conversations:read` y se responden con `messages:send`, como WhatsApp. Mira la [guía de Instagram](/es/developers/guides/instagram/).

## Mínimo privilegio

- Una clave **por integración** (CRM, Zapier, un script, un asistente IA). Revocar una no rompe las demás, y el dashboard muestra cuándo se usó cada una por última vez.
- Un panel o un informe solo necesita scopes de lectura. Concede `messages:send` solo a la integración que de verdad envía mensajes.
- Concede `prompts:write` solo a una integración o a un asistente que deba cambiar lo que dicen tus agentes. Solo con `prompts:read` puede explicar una respuesta sin poder cambiar nada.
- Las claves que das a un asistente IA a través del [servidor MCP](/es/developers/mcp/) merecen el mismo cuidado: el asistente solo puede hacer lo que la clave permite.

## Rotar una clave

1. En **Configuración**, luego **API y MCP**, haz clic en **Crear una clave** con los mismos scopes que la antigua.
2. Pon la clave nueva en tu integración y compruébala con `GET /me`.
3. Haz clic en **Revocar** en la clave antigua, luego **Revocar para siempre**. Deja de funcionar en menos de un minuto.

Rota de inmediato si sospechas una filtración: una clave pegada en un chat, un ticket o un repositorio público.

## Una clave para la API y el servidor MCP

El [servidor MCP](/es/developers/mcp/) no tiene cuentas propias. Cada llamada a una herramienta es una llamada a la API REST con tu clave, así que los scopes, los límites de peticiones y las reglas anti-ban de abajo se aplican exactamente igual. Revoca la clave y el asistente también pierde el acceso.

## Límites de peticiones

Las peticiones se cuentan **por espacio y por minuto**, todas las claves juntas. El límite depende de tu plan:

| Plan | Peticiones por minuto |
|---|---|
| Social | 30. Listas, grupos, enlaces y webhooks necesitan un plan de WhatsApp: `403 not_in_plan` |
| Free | 60 |
| Starter | 120 |
| Business | 300 |
| Scale | 1000 |

Cada respuesta lleva tres cabeceras:

| Cabecera | Significado |
|---|---|
| `X-RateLimit-Limit` | El límite de tu plan para la ventana actual. |
| `X-RateLimit-Remaining` | Peticiones que quedan en la ventana. |
| `X-RateLimit-Reset` | Cuándo se reinicia la ventana, en ISO 8601. |

Pasado el límite recibes `429 rate_limited` con una cabecera `Retry-After` en segundos. Espera ese tiempo y reintenta.

Los envíos de mensajes tienen una **cuota diaria separada por número de WhatsApp**, indicada en las cabeceras `X-Quota-*`. Mira [Errores, límites e idempotencia](/es/developers/errors/).

## Aislamiento de espacios

Una clave solo ve el espacio al que pertenece. Si pides un id que existe pero pertenece a otro espacio, la API responde `404 not_found`, igual que para un id que no existe. Nunca responde `403`, así que un id ajeno no se distingue de uno desconocido.

## Relacionado

- [Inicio rápido](/es/developers/quickstart/)
- [Errores, límites e idempotencia](/es/developers/errors/)
- [Servidor MCP](/es/developers/mcp/)
- [Equipo y roles en el dashboard](/es/dashboard/team/)
