# Autenticación

> Cómo autenticar la API de watsi con claves wats_live_, qué permite cada alcance, quién puede emitirlos y los límites de tasa por clave y por IP.

Source: https://docs.watsi.ai/guides/authentication

Cada solicitud a la API lleva una clave de API como token bearer. La clave pertenece a **un espacio de trabajo** y sólo ve los datos de ese espacio; lo que puede hacer ahí lo deciden sus **alcances**.

```http
Authorization: Bearer wats_live_…
```

## Crear una clave

### Abre Claves API

Ve a [watsi.ai/workspace/settings/api-keys](https://watsi.ai/workspace/settings/api-keys) (**Configuración → Desarrollador → Claves API**). Por defecto sólo propietarios y administradores pueden crear y revocar claves.

### Elige los alcances

Ponle un nombre que diga dónde se usa («CRM producción») y marca los permisos. Los de lectura vienen marcados; los de escritura que ofrece la pantalla los activas tú. Da a cada integración sólo lo que necesita.

### Copia la clave

Empieza por `wats_live_` y se muestra **una sola vez**. Guárdala en tu gestor de secretos. Si la pierdes, crea otra y revoca la anterior.

## Alcances

Un alcance tiene la forma `<dominio>:read` o `<dominio>:write`. Cada ruta exige uno o más; si exige varios, la clave necesita **todos**. La tabla se genera del catálogo de alcances y de las rutas que el servidor monta, así que siempre coincide con lo que la API exige.

| Alcance | Cómo se obtiene | Qué permite | Rutas |
| --- | --- | --- | --- |
| `contacts:read` | Activado por defecto | Leer contactos. | `GET contacts/channels`, `GET contacts/list`, `GET contacts/pending-merges` |
| `conversations:read` | Activado por defecto | Leer conversaciones, mensajes y búsquedas de mensajes. | `GET conversations/get`, `GET conversations/list`, `GET conversations/notes`, `GET messages/search`, `GET quick-replies/list` |
| `scheduling:read` | Activado por defecto | Leer citas y sus estadísticas. | `GET appointment-types`, `GET appointment-types/schedule`, `GET appointments/list`, `GET appointments/stats`, `GET calendar/blocks`, `GET spaces`, `GET spaces/blocks` |
| `analytics:read` | Activado por defecto | Leer analíticas: resumen, escalamientos, agentes, perfilamiento, origen. | `GET analytics/ads-pipeline-funnel`, `GET analytics/agent-performance`, `GET analytics/at-risk`, `GET analytics/booking-failures`, `GET analytics/content`, `GET analytics/content/audience`, `GET analytics/escalations`, `GET analytics/export`, `GET analytics/funnel-conversion`, `GET analytics/lead-attribution`, `GET analytics/meta-ads`, `GET analytics/overview`, `GET analytics/profiling-report` |
| `billing:read` | Activado por defecto | Leer plan, créditos y pagos. | `GET billing/credit-usage`, `GET billing/payment-history`, `GET billing/status`, `GET lifecycle/case-file` |
| `workspace:read` | Activado por defecto | Leer ajustes y miembros del espacio de trabajo. | `GET appointments/stats`, `GET workspace/members`, `GET workspace/operator-commands`, `GET workspace/settings` |
| `integrations:read` | Activado por defecto | Leer canales e integraciones conectados. | `GET automations/comment-rules`, `GET automations/comment-rules/activity`, `GET workspace/google-ads/conversion-actions`, `GET workspace/integrations` |
| `agents:read` | Activado por defecto | Leer agentes, su configuración y la de llamadas. | `GET agents/config`, `GET agents/learned-answers`, `GET agents/learned-answers/similar`, `GET agents/list`, `GET agents/versions`, `GET voice/calls`, `GET voice/catalog`, `GET voice/config`, `GET voice/diagnose` |
| `resources:read` | Activado por defecto | Leer la biblioteca de recursos. | `GET resources/get`, `GET resources/list` |
| `templates:read` | Activado por defecto | Leer plantillas de WhatsApp. | `GET templates/search` |
| `lifecycle:read` | Activado por defecto | Leer expedientes y transcripciones de llamadas (uso interno de watsi). | `GET lifecycle/ads`, `GET lifecycle/case-file`, `GET lifecycle/transcript` |
| `quotes:read` | Activado por defecto | Leer cotizaciones, las unidades por cotizar y los esquemas de venta. | `GET quotes/contract`, `GET quotes/contract-templates`, `GET quotes/get`, `GET quotes/list`, `GET quotes/pdf-link`, `GET quotes/quotable-properties`, `GET quotes/setup` |
| `meetings:read` | Activado por defecto | Leer videollamadas, sus resúmenes y transcripciones, y las próximas. | `GET meetings/assistant-settings`, `GET meetings/get`, `GET meetings/search`, `GET meetings/summary`, `GET meetings/transcript`, `GET meetings/upcoming` |
| `campaigns:read` | Lectura que marcas aparte al crear la clave | Leer campañas de WhatsApp, sus números y a quién llegó cada envío. | `GET campaigns/get`, `GET campaigns/list`, `GET campaigns/recipients` |
| `tickets:read` | Lectura que marcas aparte al crear la clave | Leer los tickets de soporte, su historial y sus notas, y los tipos de ticket. Se pide aparte. | `GET tickets`, `GET tickets/detail`, `GET tickets/types` |
| `leads:read` | Lectura que marcas aparte al crear la clave | Leer los leads de tus formularios, con su teléfono, correo y respuestas. Se pide aparte, y leads:write no lo incluye. | `GET leads`, `POST leads/refresh` |
| `contacts:write` | Lo marcas al crear la clave | Crear o actualizar contactos. | `POST contacts/assign-advisor`, `POST contacts/channels/add`, `POST contacts/channels/remove`, `POST contacts/create`, `POST contacts/pending-merges/reject`, `POST contacts/update` |
| `agents:write` | Lo marcas al crear la clave | Crear y configurar agentes, asignación y llamadas. | `POST agents/assignment`, `POST agents/create`, `POST agents/funnel-stages/google-ads-conversion`, `POST agents/product-faqs`, `POST agents/test`, `POST agents/update`, `POST agents/versions/publish`, `POST agents/versions/rename`, `POST agents/versions/restore`, `POST attachments/create-upload`, `POST attachments/finalize`, `POST attachments/import-url`, `POST voice/config`, `POST voice/phone-number-requests/confirm`, `POST voice/phone-number-requests/prepare` |
| `knowledge:write` | Lo marcas al crear la clave | Agregar y quitar documentos de conocimiento. | `POST agents/knowledge`, `POST agents/knowledge/delete`, `POST agents/knowledge/qa-import`, `POST agents/knowledge/retrain`, `POST agents/knowledge/website`, `POST agents/learned-answers/create`, `POST agents/learned-answers/delete`, `POST agents/learned-answers/dismiss`, `POST agents/learned-answers/edit`, `POST agents/learned-answers/save` |
| `scheduling:write` | Lo marcas al crear la clave | Definir horarios de los miembros. | `POST appointment-types/breaks/create`, `POST appointment-types/breaks/delete`, `POST appointment-types/breaks/update`, `POST appointment-types/create`, `POST appointment-types/members/add`, `POST appointment-types/members/remove`, `POST appointment-types/update`, `POST appointment-types/weekly-rules/set`, `POST appointments/attendance`, `POST appointments/book`, `POST appointments/book/confirm`, `POST appointments/cancel`, `POST appointments/cancel/confirm`, `POST appointments/requests/accept`, `POST appointments/requests/accept/confirm`, `POST appointments/requests/decline`, `POST appointments/requests/decline/confirm`, `POST appointments/reschedule`, `POST appointments/reschedule/confirm`, `POST appointments/sale`, `POST appointments/update`, `POST appointments/update/confirm`, `POST calendar/blocks/create`, `POST calendar/blocks/delete`, `POST calendar/blocks/update`, `POST scheduling/member-schedules`, `POST spaces/blocks/create`, `POST spaces/blocks/delete`, `POST spaces/blocks/update`, `POST spaces/create`, `POST spaces/update` |
| `crm:write` | Pídelo a watsi | Poner y quitar etiquetas a contactos. | `POST crm/notes`, `POST crm/notes/edit`, `POST crm/tags`, `POST crm/tags/remove`, `POST crm/tasks`, `POST crm/tasks/update` |
| `conversations:write` | Pídelo a watsi | Asignar, resolver, escalar y pausar el agente en una conversación; notas, estados y bloqueos. | `POST contacts/block`, `POST conversations/active-agent`, `POST conversations/agent`, `POST conversations/agent-enabled`, `POST conversations/assign`, `POST conversations/escalate`, `POST conversations/notes/create`, `POST conversations/notes/delete`, `POST conversations/notes/edit`, `POST conversations/observers`, `POST conversations/read`, `POST conversations/reopen`, `POST conversations/resolve`, `POST conversations/status`, `POST conversations/statuses/create`, `POST conversations/statuses/reorder`, `POST conversations/statuses/update`, `POST conversations/unassign`, `POST quick-replies/create`, `POST quick-replies/hidden` |
| `templates:write` | Pídelo a watsi | Enviar plantillas de WhatsApp a revisión de Meta, en dos pasos. | `POST templates/submit/confirm`, `POST templates/submit/prepare` |
| `broadcast:write` | Pídelo a watsi | Mandar una plantilla aprobada a un grupo de contactos, en dos pasos, y detener el envío; guardar y editar borradores de campaña y pausar una campaña. | `POST broadcasts/cancel`, `POST broadcasts/confirm`, `POST broadcasts/prepare`, `POST campaigns/drafts/create`, `POST campaigns/drafts/update`, `POST campaigns/pause`, `POST conversations/start`, `POST conversations/start/confirm` |
| `members:write` | Pídelo a watsi | Invitar a un compañero por correo, en dos pasos, y cancelar invitaciones pendientes. | `POST team/invites/confirm`, `POST team/invites/prepare`, `POST team/invites/revoke` |
| `lifecycle:write` | Solo lo emite watsi | Registrar llamadas y mover la línea de tiempo (uso interno de watsi). | `POST lifecycle/ads/copy`, `POST lifecycle/ads/create-upload`, `POST lifecycle/ads/finalize-upload`, `POST lifecycle/ads/folders`, `POST lifecycle/ads/import-url`, `POST lifecycle/ads/move`, `POST lifecycle/ads/reorder`, `POST lifecycle/ads/update-item`, `POST lifecycle/attach-file`, `POST lifecycle/record-call`, `POST lifecycle/step` |
| `quotes:write` | Pídelo a watsi | Crear y editar cotizaciones en borrador, y cancelarlas. | `POST quotes/contract`, `POST quotes/contract/update`, `POST quotes/drafts`, `POST quotes/drafts/update`, `POST quotes/duplicate`, `POST quotes/payment-methods/update`, `POST quotes/schemes`, `POST quotes/schemes/update`, `POST quotes/status`, `POST quotes/units/update/confirm`, `POST quotes/units/update/prepare` |
| `quote_sends:write` | Pídelo a watsi | Enviar una cotización al cliente, en dos pasos: vista previa y confirmación. | `POST quotes/contract/send`, `POST quotes/contract/send/confirm`, `POST quotes/send`, `POST quotes/send/confirm` |
| `messages:write` | Lo marcas al crear la clave | Responderle al cliente en una conversación o mandarle una plantilla, en dos pasos. | `POST conversations/forward`, `POST conversations/forward/confirm`, `POST conversations/react`, `POST conversations/react/confirm`, `POST conversations/reply`, `POST conversations/reply/confirm`, `POST conversations/template`, `POST conversations/template/confirm` |
| `meetings:write` | Pídelo a watsi | Decidir en qué videollamadas entra el asistente. | `POST meetings/assistant`, `POST meetings/assistant-settings/update` |
| `automations:write` | Pídelo a watsi | Crear, editar, pausar y activar automatizaciones de comentarios; activar va en dos pasos. | `POST automations/comment-rules/activate/confirm`, `POST automations/comment-rules/activate/prepare`, `POST automations/comment-rules/create`, `POST automations/comment-rules/duplicate`, `POST automations/comment-rules/pause`, `POST automations/comment-rules/update` |
| `tickets:write` | Pídelo a watsi | Abrir tickets de soporte, tomarlos y comentarlos. | `POST tickets`, `POST tickets/claim`, `POST tickets/notes`, `POST tickets/types`, `POST tickets/types/update`, `POST tickets/update/confirm`, `POST tickets/update/prepare` |
| `notifications:write` | Pídelo a watsi | Cambiar qué avisos reciben los administradores y los miembros, por correo y push. | `POST workspace/notifications/matrix` |
| `commands:write` | Pídelo a watsi | Guardar, editar y borrar tus propios comandos del menú ⌘K. | `POST workspace/operator-commands`, `POST workspace/operator-commands/delete`, `POST workspace/operator-commands/update` |
| `workspace:write` | Pídelo a watsi | Cambiar la zona horaria y el logo del espacio de trabajo. | `POST workspace/logo`, `POST workspace/logo/upload`, `POST workspace/timezone/confirm`, `POST workspace/timezone/prepare` |

Otros alcances del catálogo, sin ruta pública todavía: `shopify:read`, `plans:read`, `leads:write`, `shopify:write`, `plans:write`.

Qué significa la columna **Cómo se obtiene**:

- **Activado por defecto**: toda clave nueva lo lleva salvo que lo desmarques.
- **Lo marcas al crear la clave**: escrituras que puedes darte tú mismo.
- **Pídelo a watsi**: escrituras que la pantalla no ofrece; el equipo de watsi puede emitirte una clave que las lleve.
- **Solo lo emite watsi**: tocan la línea de tiempo de otro espacio de trabajo, así que nunca se auto-emiten. Desde la app, al pedirlos, recibes el error `Operator-only scopes cannot be self-issued`.

> **Note**

`leads:write` autoriza el ingreso de leads entrantes por conectores dedicados, no una ruta `/v1/actions`. Las claves antiguas pueden llevar `messages:read` y `messages:write`; ninguna ruta `/v1/actions` los usa.

## El espacio de trabajo sale de la clave

Nunca mandas el espacio de trabajo: watsi lo toma de la clave. Las rutas `crm/tags` y `crm/tags/remove` aceptan un `companyId` opcional en el cuerpo por compatibilidad, pero **lo ignoran**: la etiqueta se escribe siempre en el espacio de trabajo de la clave. Puedes omitirlo; si lo mandas, tiene que ser un UUID válido.

## Errores de autenticación

| Estado | `code`         | `message`                                        | Qué hacer                                         |
| ------ | -------------- | ------------------------------------------------ | ------------------------------------------------- |
| 401    | `UNAUTHORIZED` | `Missing or malformed Authorization header`      | Manda `Authorization: Bearer <clave>`             |
| 401    | `UNAUTHORIZED` | `Invalid or expired API key`                     | La clave no existe, se revocó o venció: crea otra |
| 403    | `FORBIDDEN`    | `Missing required scope "x:read" for action "…"` | Crea una clave con ese alcance                    |

```json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required scope \"contacts:write\" for action \"createContact\""
  }
}
```

## Límites de tasa

Hay dos límites, y el primero que se alcance responde `429`:

- **60 solicitudes por minuto por clave**, en ventanas de minuto de reloj.
- **100 solicitudes por minuto por dirección IP**, antes de leer la clave.

Cada respuesta autenticada trae el estado del límite de la clave:

| Encabezado              | Significado                                           |
| ----------------------- | ----------------------------------------------------- |
| `X-RateLimit-Limit`     | Solicitudes permitidas por ventana (60)               |
| `X-RateLimit-Remaining` | Las que te quedan en esta ventana                     |
| `X-RateLimit-Reset`     | Cuándo empieza la siguiente ventana, en segundos Unix |
| `Retry-After`           | En un `429`, los segundos que faltan para reintentar  |

Al pasar cualquiera de los dos recibes `429` con `code: "RATE_LIMITED"`. Espera a `X-RateLimit-Reset` (o `Retry-After`) antes de reintentar; si necesitas más volumen, reparte las extracciones grandes a lo largo del minuto. Si el contador no responde, watsi falla cerrado con `503 SERVICE_UNAVAILABLE`: reintenta en unos segundos.

## Buenas prácticas

- **Una clave por integración**, con nombre. Así revocas una sin tumbar las demás.
- **Sólo los alcances necesarios.** Una clave de reportes no necesita escrituras.
- **Nunca en el navegador ni en una app móvil.** La clave es secreta; llama a la API desde tu servidor.
- **Rota si se filtra.** Crea la nueva, despliégala y revoca la vieja; revocar no se puede deshacer.
- **Registra `X-Request-Id`.** Cada respuesta lo trae; con él soporte encuentra tu solicitud en los registros.

> **Info**

Los clientes de IA que se conectan al [servidor MCP](/mcp) pueden usar esta misma clave o iniciar sesión con OAuth 2.1, que pide los alcances en una pantalla de consentimiento.
