Autenticación y permisos

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 ¿Confirmar?. El dashboard confirma: Clave revocada. Efectivo en menos de un minuto. Revocarla corta la API REST y el servidor MCP a la vez.

Enviar la clave

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

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) 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 ya contactado; 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}

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

Tres scopes son nuevos

blocklist:manage, team:read y links:read llegaron con los endpoints de contactos bloqueados, equipo y enlaces rastreados. Una clave creada antes no los lleva: crea una clave nueva si necesitas esos endpoints. Mira las guías de contactos bloqueados, equipo y enlaces rastreados.

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.
• Las claves que das a un asistente IA a través del servidor 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 ¿Confirmar?. 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 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
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.

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
• Errores, límites e idempotencia
• Servidor MCP
• Equipo y roles en el dashboard