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.
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.
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
- Abre el menú Account (tu avatar) y elige API keys.
- Selecciona Create key, dale un nombre que reconozcas más tarde y, si quieres, una fecha de caducidad.
- Copia el token. Se muestra una sola vez; Veyra solo guarda un hash.
O desde la API, con una clave que ya tengas:
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
- Abre el agente y su pestaña API keys.
- Selecciona Create key y ponle el nombre del lugar donde se usará.
- Copia el token; se muestra una sola vez.
O llama a Create an agent API key:
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 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:
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. |