Autenticación y claves
Cómo autenticarte con claves de API de Vemudo, qué significan los entornos test y live, los permisos send, read y full, y los límites de peticiones.
Por Equipo Vemudo · Actualizado el
https://api.vemudo.com/v1 y se autentica con una clave de API en la cabecera Authorization:
curl https://api.vemudo.com/v1/me \
-H "Authorization: Bearer $VEMUDO_API_KEY"Formato de las claves
vm_<entorno>_<identificador><secreto>, por ejemplo vm_live_.... El comienzo (vm_live_ más el identificador) es el prefijo, que el panel enseña para que reconozcas cada clave. El secreto completo solo se muestra al crearla: Vemudo guarda únicamente un hash, así que no puede recuperarlo después. Si lo pierdes, crea otra clave y revoca la antigua.
Entornos
test: no llama al proveedor de correo. Los emails se aceptan, pasan por los mismos estados y eventos y las entregas se simulan. Sirve para desarrollar y para pruebas automáticas. No consume cuota del plan.live: envía de verdad. Solo se puede crear con la organización activa y un dominio verificado (409 live_requires_verified_domainsi falta).
test nunca es visible con una live, ni al revés. Los webhooks también son por entorno: un endpoint creado con una clave test solo recibe eventos de emails test.
Permisos (scopes)
send | |
read | |
full | send y read. |
send y read no se incluyen entre sí. Una clave sin el permiso necesario recibe 403 insufficient_scope. GET /v1/me funciona con cualquier scope.
send. Para un panel de métricas o un asistente de IA que solo consulta, read.
Crear y revocar claves
Pueden crear y revocar claves los roles owner, admin y developer. Cada organización tiene hasta 25 claves activas y puede crear hasta 20 por hora. Revocar es inmediato y se permite en cualquier estado de la organización, para que puedas cortar una clave filtrada sin esperar. Crear y revocar claves queda registrado en la auditoría de la organización (nunca el secreto).
Límite de peticiones
RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Al superarlo recibes 429 rate_limited con una cabecera Retry-After: espera ese tiempo y reintenta.
GET /v1/stats y GET /v1/account tienen además un límite de 60 peticiones por minuto por clave.
Errores de autenticación
401 | invalid_api_key | |
403 | insufficient_scope | |
403 | organization_not_active | test. |
429 | rate_limited | Retry-After. |
La misma clave en /v1 y en el MCP remoto
https://api.vemudo.com/v1 y para POST https://api.vemudo.com/mcp (MCP y asistentes de IA): mismos scopes, mismo entorno (test/live) y el mismo bloqueo de 15 minutos por IP tras demasiados intentos fallidos. No hay que crear una clave distinta para el servidor MCP remoto.
/mcp admite además OAuth 2.1: el cliente de IA abre el navegador, entras en Vemudo y eliges organización, entorno y permisos, sin copiar ninguna clave (ver Conectar con OAuth). Los tokens OAuth (vmo_at_...) solo valen en /mcp: en /v1 responden 401.
403 | api_key_blocked | |
403 | agents_blocked |
Buenas prácticas
Guarda la clave en una variable de entorno o en un gestor de secretos. No uses claves de Vemudo en aplicaciones de navegador o móvil: la API no admite CORS y la clave quedaría visible. Llama siempre desde tu servidor. Usa una clave por aplicación o entorno (CI, producción, asistente de IA) para poder revocarlas por separado. Rota las claves con regularidad: crea la nueva, despliega, revoca la antigua. Una cookie de sesión del panel no autentica la API: /v1ignora las cookies.