Autenticación

Todas las solicitudes a la API de watsi requieren un token Bearer. Esta guía explica cómo crear claves de API, autenticar solicitudes y mantener seguras sus credenciales.

Cómo crear una clave de API

Inicie sesión en el panel de watsi
Vaya a Settings → API Keys
Haga clic en Generate new key
Copie la clave de inmediato — solo se muestra una vez

Importante: Almacene su clave de API en un lugar seguro, como una variable de entorno o un gestor de secretos. Nunca incluya claves de API en el control de versiones.

Cómo usar su clave de API

Incluya la clave de API en el encabezado Authorization de cada solicitud utilizando el esquema Bearer:

curl https://api.watsi.ai/api/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY"

Si la clave falta o no es válida, la API devuelve una respuesta 401 Unauthorized:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

Alcances de las claves de API

Cada clave de API está limitada a un único espacio de trabajo. La clave hereda los permisos del usuario que la creó y puede acceder a todos los recursos dentro de ese espacio de trabajo.

Alcance	Acceso
`conversations`	Listar, leer y administrar conversaciones
`customers`	Listar, leer, crear y actualizar contactos
`messages`	Enviar mensajes dentro de conversaciones abiertas
`templates`	Listar y administrar plantillas de mensajes de WhatsApp
`tags`	Crear, listar y asignar etiquetas a contactos
`users`	Listar a los miembros del equipo del espacio de trabajo

Autenticación de MCP

El servidor de MCP vive en un único endpoint y habla Streamable HTTP, sin estado. No existe un endpoint /sse.

POST https://mcp.watsi.ai/mcp

La misma clave de API funciona para las conexiones de MCP. Los clientes que hablan Streamable HTTP de forma nativa (Cursor, Windsurf, agentes personalizados) toman la URL y el encabezado directamente:

{
  "mcpServers": {
    "watsi": {
      "url": "https://mcp.watsi.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Los clientes web que no pueden enviar un encabezado propio — Claude.ai y ChatGPT — usan en su lugar OAuth 2.1 con registro dinámico de clientes, que ya está disponible: agregue la URL como conector personalizado, inicie sesión en watsi, elija el espacio de trabajo y apruebe los alcances en la pantalla de consentimiento.

Las herramientas se proyectan desde el mismo contrato de acciones que estos endpoints REST, así que un alcance significa lo mismo en ambos. La mayor parte del catálogo lee; un conjunto pequeño de herramientas de configuración del agente escribe (crear un agente, actualizar su configuración, agregar o eliminar conocimiento, definir la política de asignación, definir los horarios de los miembros, actualizar la configuración de llamadas) y cada una exige un alcance explícito agents:write, knowledge:write o scheduling:write. El selector de claves del panel no ofrece esos tres (sí ofrece otros alcances de escritura como messages:write y contacts:write), por lo que una clave del panel puede escribir mensajes y contactos, pero no puede cambiar la configuración del agente.

El catálogo autoritativo es el que el servidor publica por tools/list una vez conectado — no se fija en esta guía, porque una herramienta cuyo servicio de respaldo no está cableado en un entorno se retira allí en lugar de anunciarse y fallar. Consulte la guía de MCP para la configuración completa.

Buenas prácticas de seguridad

Rote las claves con regularidad — genere una nueva clave y revoque la anterior de forma periódica
Use variables de entorno — nunca codifique las claves directamente en el código fuente de la aplicación
Restrinja el uso al lado del servidor — nunca exponga las claves de API en código del lado del cliente ni en solicitudes del navegador
Supervise el uso — revise la actividad de las claves de API en el panel y revoque las claves que ya no necesite
Use solo HTTPS — todas las solicitudes a la API deben realizarse por HTTPS. Las solicitudes HTTP sin cifrar son rechazadas

Límites de tasa

La API permite 100 solicitudes por minuto por clave de API. Cuando supera el límite, la API devuelve 429 Too Many Requests con un encabezado Retry-After que indica cuántos segundos debe esperar.

Consulte la guía de manejo de errores para conocer estrategias de reintento.