La API REST de Zenovay está documentada en docs.zenovay.com. Cada solicitud se autentica con un token Bearer (una «clave API») que generas en el panel.
Información
La API REST es una función de pago. Está disponible en los planes Pro, Scale y Enterprise. En el plan gratuito no puedes crear ni usar claves API. Actualiza desde Configuración → Facturación para desbloquearlo.
Cómo se organizan las claves API
Las claves Zenovay son personales: cada clave la creas tú y actúa en tu nombre, en los equipos (espacios de trabajo) a los que decides darle acceso. Las gestiona en tu cuenta y se revocan automáticamente cuando pierdes acceso a un equipo.
Cuando creas una clave decides dos cosas:
- Qué permisos tiene — acceso completo, o cualquier combinación de lectura, escritura y administración.
- A qué equipos puede llegar — todos los equipos a los que perteneces, o un subconjunto específico.
Los propietarios y administradores del espacio de trabajo pueden decidir quién puede crear claves que alcancen el espacio de trabajo (todos los miembros, solo propietarios y administradores, o nadie). Esa gobernanza vive en la página de API del espacio de trabajo en Configuración → Seguridad y acceso → Claves API.
Generar una clave API
Abre la configuración de seguridad de tu cuenta
En
app.zenovay.com, ve a Configuración → Cuenta → Seguridad y acceso, luego encuentra la tarjeta Claves API.Crea una nueva clave
Haz clic en Crear clave API y dale un nombre que describa la integración (p. ej.
Alertas Slack,Exportación interna de datos). Los nombres pueden tener hasta 64 caracteres.Elige los permisos
- Acceso completo — lectura y escritura en todo lo que pueda alcanzar la clave.
- Seleccionar — elige cualquier combinación de Lectura (puntos de terminación GET de analytics), Escritura (POST/PATCH/DELETE) y Admin (puntos de terminación solo para administrador). Estos son independientes: una clave de solo lectura, un receptor de webhook de solo escritura y una clave de automatización de solo administrador son todos válidos.
El alcance Admin solo puede dirigirse a equipos donde eres propietario o administrador.
Elige el acceso del equipo
- Todos los equipos — la clave funciona en todos los equipos a los que perteneces actualmente.
- Seleccionar equipos — bloquea la clave a equipos específicos. Ideal para limitar una clave a un espacio de trabajo.
Copia la clave una sola vez
La clave comienza con
zv_y se muestra solo una vez en el momento de creación. Cópiala inmediatamente en tu gestor de secretos. Solo almacenamos un hash — no podemos recuperar una clave perdida.
Solicitud hello-world
Cada llamada a la API envía la clave como token Bearer en el encabezado Authorization.
curl https://api.zenovay.com/api/external/v1/websites \
-H "Authorization: Bearer zv_your_actual_key_here"
Una respuesta correcta devuelve los sitios a los que la clave tiene acceso en JSON. Si la clave es inválida o está revocada, recibirás 401 Unauthorized. Si tu plan no incluye acceso a la API, recibirás 403.
Límites de tasa
Las solicitudes de API están limitadas por plan:
| Plan | Solicitudes por minuto |
|---|---|
| Free | Sin acceso a API |
| Pro | 30 |
| Scale | 60 |
| Enterprise | 120 |
Las respuestas incluyen los encabezados X-RateLimit-Limit y X-RateLimit-Remaining, para que puedas leerlos y reducir el ritmo cuando te acerques al límite. Consulta Límites de tasa de la API para más detalles.
Revocar claves
- Revocar — abre la clave bajo Configuración → Cuenta → Seguridad y acceso, luego elige Revocar. La clave deja de funcionar inmediatamente.
- Editar — puedes renombrar una clave o ajustar sus permisos y acceso al equipo desde el mismo lugar.
- Auditoría — cada clave muestra cuándo se creó. Si no reconoces una clave o ya no usas la integración detrás, revócala.
Para rotar una clave, crea una nueva, despliégala, luego revoca la antigua.
Servidor MCP
Zenovay también habla el Model Context Protocol, para que puedas conectar Claude Desktop, Cursor o cualquier cliente MCP directamente a tu análisis. MCP está disponible en todos los planes (Free, Pro, Scale y Enterprise), con límites de consultas diarias por plan. No usa una clave API REST — en su lugar apuntas tu cliente a https://api.zenovay.com/mcp y lo autorizas una vez a través de OAuth (sin clave que copiar). Puedes revisar y revocar clientes MCP conectados bajo Configuración → Cuenta → Seguridad y acceso. Consulta la documentación de MCP en el sitio del desarrollador para la configuración completa y la lista de herramientas.
Buenas prácticas
- Nunca commits una clave en un repositorio público. Almacena claves en un gestor de secretos, no en el control de versiones.
- Una clave por integración. Si un proveedor se ve comprometido, solo revocas su clave.
- Usa los permisos más estrictos que la integración necesita. Opta por solo lectura a menos que tenga que escribir.
- Limita por equipo para integraciones que solo tocan un espacio de trabajo, para que una clave filtrada no pueda llegar al resto.