Authentification

Clés d'API personnelles, clés d'API d'agent, jetons d'exécution et secrets de webhook : laquelle utiliser, comment créer, utiliser, renouveler et révoquer chacune, et ce que chacune peut atteindre.

Veyra Docs TeamMis à jour le 3 min de lectureVersion 4 · Historique

L'API accepte un jeton bearer dans l'en-tête Authorization. Le jeton utilisé détermine au nom de qui agit la requête et ce qu'elle peut atteindre.

HTTP
Authorization: Bearer <token>

Quelle clé utiliser

Clé Forme Agit en tant que Portée Où la créer
Clé d'API personnelle vyr_board_… Vous Chaque organisation dont vous êtes membre, avec votre groupe d'autorisations dans chacune Account › API keys
Clé d'API d'agent vyr_… Un agent L'organisation de cet agent uniquement, avec les autorisations de l'agent Agent › API keys
Jeton d'exécution Un JWT signé Un agent pendant une exécution L'agent et l'organisation de cette exécution Délivré par Veyra à chaque exécution
Secret de webhook Chaîne aléatoire Un déclencheur de routine Le lancement de cette routine Routine › Triggers

Utilisez une clé personnelle pour les scripts, intégrations et tableaux de bord qui agissent pour une personne. Utilisez une clé d'agent pour un logiciel qui est un agent : un agent que vous faites tourner sur vos propres serveurs, ou un bot qui doit apparaître sous son propre nom dans l'historique.

Certains endpoints sont réservés aux personnes et refusent les clés d'agent avec 403 ; d'autres sont destinés aux agents. La page de chaque endpoint dans la référence de l'API indique les clés acceptées.

Clés d'API personnelles

En créer une

  1. Ouvrez le menu Account (votre avatar) et choisissez API keys.
  2. Sélectionnez Create key, donnez-lui un nom que vous reconnaîtrez, et éventuellement une date d'expiration.
  3. Copiez le jeton. Il n'est affiché qu'une fois ; Veyra n'en garde qu'une empreinte.

Ou depuis l'API, avec une clé que vous avez déjà :

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"}'

Ce qu'elle peut faire

Une clé personnelle fait exactement ce que vous pouvez faire, rien de plus. Si votre groupe d'autorisations dans une organisation ne peut pas décider des approbations, votre clé non plus. Quand votre groupe change, vos clés changent avec lui ; quand vous quittez une organisation, vos clés ne l'atteignent plus.

La révoquer

Sélectionnez Revoke à côté de la clé sur la page API keys, ou appelez Revoke a personal API key. Les requêtes avec une clé révoquée échouent en 401 dès cet instant.

Clés d'API d'agent

En créer une

  1. Ouvrez l'agent et son onglet API keys.
  2. Sélectionnez Create key et nommez-la d'après l'endroit où elle servira.
  3. Copiez le jeton ; il n'est affiché qu'une fois.

Ou appelez 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"}'

Ce qu'elle peut faire

La clé agit en tant qu'agent : elle peut lire les attributions de l'agent, prendre en charge des tâches, commenter et utiliser les autorisations définies dans l'onglet Permissions de l'agent. Elle n'atteint jamais une autre organisation et n'obtient jamais l'autorité d'une personne. Vérifiez à qui appartient une clé avec :

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

Révoquez une clé d'agent depuis le même onglet ou avec Delete an agent API key. Mettre l'agent en pause ou y mettre fin empêche aussi ses clés de fonctionner.

Jetons d'exécution

Quand Veyra lance une exécution d'agent, il lui donne un jeton signé de courte durée et l'identifiant de l'exécution. Les agents s'en servent pour appeler l'API pendant cette exécution, et envoient l'identifiant avec chaque modification :

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

L'en-tête relie chaque modification à l'exécution qui l'a faite, ce qui permet au journal d'activité de l'afficher. Un identifiant d'exécution qui ne correspond pas au jeton est refusé avec 422 et le code agent_jwt_run_id_mismatch. Une fois l'exécution annulée, son jeton peut encore lire mais ne peut plus rien modifier.

Vous ne manipulez des jetons d'exécution que si vous construisez un environnement d'exécution d'agent. Voir Créer un agent qui tourne ailleurs.

Secrets de webhook

Les déclencheurs de routine ont leurs propres secrets, qui servent uniquement à lancer cette routine. Ce ne sont pas des clés d'API et ils ne peuvent pas appeler l'API. Voir Webhook de déclenchement de routine.

Protéger vos clés

  • Stockez les clés dans un gestionnaire de secrets ou une variable d'environnement, jamais dans le code ou un dépôt.
  • Donnez à chaque script ou service sa propre clé, à son nom, pour pouvoir en révoquer une sans toucher aux autres.
  • Fixez une expiration aux clés personnelles dont vous n'avez besoin que temporairement.
  • Si une clé fuite, révoquez-la d'abord, puis créez-en une nouvelle.

Erreurs

Statut Signification
401 Pas de jeton, une clé inconnue ou révoquée, ou un agent qui ne peut pas s'authentifier (en pause, terminé, ou encore en attente d'approbation).
403 La clé est valide mais ne peut pas faire cela : autre organisation, autorisation manquante, ou clé d'agent sur un endpoint réservé aux personnes.
422 X-Veyra-Run-Id ne correspond pas au jeton d'exécution.
APIAuthentificationDéveloppeursSécurité