Saltar al contenido

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

Toda la API pública cuelga de https://api.vemudo.com/v1 y se autentica con una clave de API en la cabecera Authorization:

bash
curl https://api.vemudo.com/v1/me \
  -H "Authorization: Bearer $VEMUDO_API_KEY"

Formato de las claves

Una clave tiene la forma 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

Cada clave pertenece a un entorno y solo ve los recursos de ese entorno.

  • 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_domain si falta).

Un email enviado con una clave 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)

ScopePara qué sirve
sendEnviar, cancelar y consultar los emails creados con esa misma clave.
readSolo lectura: consultar emails, eventos, estadísticas, dominios, contactos, campañas, plantillas, bajas y webhooks de toda la organización. No puede enviar ni modificar nada.
fullTodo lo anterior, más las escrituras sobre bajas y webhooks. Incluye 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.

Elige siempre el scope mínimo. Para una integración que solo envía transaccionales, 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

El límite es de 10 peticiones por segundo por organización, compartido por todas sus claves. Las respuestas autenticadas llevan las cabeceras 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.

Hay también un límite de intentos fallidos de autenticación por dirección IP (30 por minuto). Una clave válida no se bloquea por él.

Errores de autenticación

RespuestaCódigoSignificado
401invalid_api_keyFalta la cabecera, el formato es incorrecto, la clave no existe o está revocada. El mensaje es siempre el mismo para no revelar cuál de los casos es.
403insufficient_scopeLa clave es válida pero su scope no permite esta operación.
403organization_not_activeLa organización está cerrada o suspendida. En revisión o pausada solo funcionan las claves test.
429rate_limitedDemasiadas peticiones. Respeta Retry-After.

La misma clave en /v1 y en el MCP remoto

Una clave de API vale igual para 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.

Los dos 403 de bloqueo son los mismos en los dos sitios:

RespuestaCódigoSignificado
403api_key_blockedLa propia clave está bloqueada por la plataforma.
403agents_blockedLa organización tiene los agentes (API y MCP) bloqueados.

Los dos se resuelven escribiendo a soporte: el panel no tiene un botón para desbloquearlos.

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: /v1 ignora las cookies.