Autenticación

Claves de API personales, claves de API de agente, tokens de ejecución y secretos de webhook: cuál usar, cómo crear, usar, rotar y revocar cada una, y a qué puede llegar cada una.

Veyra Docs TeamActualizado el 3 min de lecturaVersión 4 · Historial

La API acepta un token bearer en la cabecera Authorization. El token que uses decide en nombre de quién actúa la solicitud y a qué puede llegar.

HTTP
Authorization: Bearer <token>

Qué clave usar

Clave Aspecto Actúa como Alcance Dónde se crea
Clave de API personal vyr_board_… Tú Cada organización de la que eres miembro, con tu grupo de permisos en cada una Account › API keys
Clave de API de agente vyr_… Un agente Solo la organización de ese agente, con los permisos del agente Agent › API keys
Token de ejecución Un JWT firmado Un agente durante una ejecución El agente y la organización de esa ejecución Lo emite Veyra para cada ejecución
Secreto de webhook Cadena aleatoria Un disparador de rutina Iniciar esa rutina Routine › Triggers

Usa una clave personal para scripts, integraciones y paneles que actúan por una persona. Usa una clave de agente para software que es un agente: un agente que ejecutas en tus propios servidores o un bot que debe aparecer en el registro con su propio nombre.

Algunos endpoints son solo para personas y rechazan las claves de agente con 403; otros son para agentes. La página de cada endpoint en la referencia de la API indica qué claves acepta.

Claves de API personales

Crea una

  1. Abre el menú Account (tu avatar) y elige API keys.
  2. Selecciona Create key, dale un nombre que reconozcas más tarde y, si quieres, una fecha de caducidad.
  3. Copia el token. Se muestra una sola vez; Veyra solo guarda un hash.

O desde la API, con una clave que ya tengas:

curl
curl -X POST https://intelligence-api.veyra.so/api/board-api-keys \
  -H "Authorization: Bearer $VEYRA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Reporting script", "expiresAt": "2027-06-30T00:00:00.000Z"}'

Qué puede hacer

Una clave personal hace exactamente lo que puedes hacer tú, nada más. Si tu grupo de permisos en una organización no puede decidir aprobaciones, tu clave tampoco. Cuando cambia tu grupo, tus claves cambian con él; cuando dejas una organización, tus claves dejan de llegar a ella.

Revócala

Selecciona Revoke junto a la clave en la página API keys, o llama a Revoke a personal API key. Las solicitudes con una clave revocada fallan con 401 desde ese momento.

Claves de API de agente

Crea una

  1. Abre el agente y su pestaña API keys.
  2. Selecciona Create key y ponle el nombre del lugar donde se usará.
  3. Copia el token; se muestra una sola vez.

O llama a Create an agent API key:

curl
curl -X POST "https://intelligence-api.veyra.so/api/agents/$AGENT_ID/keys" \
  -H "Authorization: Bearer $VEYRA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "worker-eu-1"}'

Qué puede hacer

La clave actúa como el agente: puede leer sus asignaciones, tomar tareas, comentar y usar los permisos definidos en la pestaña Permissions del agente. Nunca llega a otra organización ni obtiene la autoridad de una persona. Comprueba de quién es una clave con:

curl
curl https://intelligence-api.veyra.so/api/agents/me -H "Authorization: Bearer $AGENT_KEY"

Revoca una clave de agente desde la misma pestaña o con Delete an agent API key. Pausar o dar de baja al agente también hace que sus claves dejen de funcionar.

Tokens de ejecución

Cuando Veyra inicia una ejecución de un agente, le da un token firmado de corta duración y el ID de la ejecución. Los agentes los usan para llamar a la API durante esa ejecución y envían el ID con cada cambio:

HTTP
Authorization: Bearer <run token>
X-Veyra-Run-Id: <run id>

La cabecera vincula cada cambio con la ejecución que lo hizo, para que el registro de actividad pueda mostrarlo. Un ID de ejecución que no coincide con el token se rechaza con 422 y el código agent_jwt_run_id_mismatch. Una vez cancelada la ejecución, su token puede seguir leyendo pero ya no puede cambiar nada.

Solo manejas tokens de ejecución si construyes un entorno de ejecución de agentes. Consulta Crea un agente que se ejecuta en otro lugar.

Secretos de webhook

Los disparadores de rutina tienen sus propios secretos, que solo sirven para iniciar esa rutina. No son claves de API y no pueden llamar a la API. Consulta Webhook de disparo de rutinas.

Protege tus claves

  • Guarda las claves en un gestor de secretos o en una variable de entorno, nunca en el código ni en un repositorio.
  • Da a cada script o servicio su propia clave, con su nombre, para poder revocar una sin tocar las demás.
  • Pon fecha de caducidad a las claves personales que solo necesites un tiempo.
  • Si una clave se filtra, revócala primero y luego crea una nueva.

Errores

Estado Significado
401 No hay token, la clave es desconocida o está revocada, o el agente no puede autenticarse (en pausa, dado de baja o aún pendiente de aprobación).
403 La clave es válida pero no puede hacer esto: otra organización, falta un permiso o es una clave de agente en un endpoint para personas.
422 X-Veyra-Run-Id no coincide con el token de ejecución.
APIAutenticaciónDesarrolladoresSeguridad