Aller au contenu

API

L'API HTTP expose les mêmes opérations que l'interface et la CLI. Le contrat lisible par machine est servi par l'instance : GET /api/v1/openapi.json (OpenAPI 3.1, généré du registre des opérations). La référence générée en résume les routes fixes et les erreurs.

Authentification

Envoyez un jeton dans l'en-tête Authorization: Bearer <jeton>.

Jeton Préfixe Pour qui Durée
Jeton personnel hpat_ un humain, via la CLI 1 à 365 jours, révocable
Clé API hsvc_ un script, n8n, un automate (compte de service) bornée par api.key_max_days, révocable
JWT de run — un agent pendant un run (900 s, renouvelable) court

Une session web (cookie) fonctionne aussi dans un navigateur, avec l'en-tête X-CSRF-Token pour les méthodes non sûres.

Appeler une opération

curl -sS -H "Authorization: Bearer $HARNESS_KEY" -H 'Content-Type: application/json' \
     -d '{"name": "helper"}' https://harness.example.org/api/v1/ops/core.agent.get

Le corps JSON est l'objet des arguments ; son schéma est dans l'OpenAPI et dans la référence des opérations. Pour découvrir ce que votre jeton peut faire : GET /api/v1/ops (liste), GET /api/v1/ops/<nom> (description), GET /api/v1/whoami.

Enveloppe de réponse

{"ok": true,  "result": { … }}
{"ok": false, "error": {"code": "denied", "message": "…"}}
HTTP error.code Sens
200 — succès
202 pending_confirmation en attente d'approbation hors bande (confirmation_id, expires_at)
400 invalid_json, invalid_input corps ou arguments invalides
401 unauthenticated jeton absent, expiré, révoqué, ou adresse source non autorisée
403 denied, reauth_required permission refusée ; ré-authentification humaine exigée
404 NotFound op ou objet inconnu (un refus de lecture est indiscernable d'une absence)
409 conflict existe déjà
500 internal erreur interne ; citez l'en-tête X-Request-Id

Le contrat OpenAPI

GET /api/v1/openapi.json est lisible sans authentification : il est dérivé du code (noms, résumés, permissions, schémas JSON), ne contient ni secret ni donnée d'instance, et permet de générer un client avant même de posséder une clé. Sans jeton il décrit les opérations du socle ; avec un jeton, s'y ajoutent les opérations de plugins que ce jeton peut appeler. Chaque opération porte x-permission, x-read-only, x-dangerous et x-human-only.

Clés API

Une clé API est le jeton hsvc_… d'un compte de service. Elle se gère dans l'administration, page Clés API (opérations core.svc.key.*) :

Propriété Effet
Rôles liés les droits de la clé : ceux des rôles liés au compte (aucun droit tant qu'aucun rôle n'est lié)
Expiration (expires_at) par défaut et au plus api.key_max_days jours (365) ; après, la clé est refusée
Dernier usage (last_used_at) mis à jour à chaque minute d'usage au plus ; repérez les clés dormantes
IP autorisées liste de CIDR (203.0.113.0/24, 2001:db8::/32) ; vide = pas de restriction. Hors liste, ou adresse inconnue : refusé
  • Le jeton n'est montré qu'une fois, à la création ou à l'émission : seul son empreinte est conservée. Perdu, il se remplace (core.svc.key.issue), ce qui invalide l'ancien.
  • Révoquer (core.svc.key.revoke) coupe la clé sans supprimer le compte ni ses rôles.
  • Renouveler (core.svc.key.limits avec days) repousse l'expiration à maintenant + days sans changer la clé.
  • Lier des rôles élargit des droits : comme pour tout élargissement, il faut être administrateur, ne jamais le faire pour soi-même, et ré-authentifier ou faire approuver l'action. Seul un super-admin peut lier admin ou superadmin.
  • Les comptes créés avant l'introduction de l'expiration n'ont pas d'échéance : réémettez leur clé pour en fixer une.
  • L'adresse source est celle vue derrière le reverse proxy de tête : l'entrée Apache n'en fait confiance que pour les proxies privés (RemoteIPInternalProxy). Derrière un proxy public, une restriction par IP ne serait pas fiable.
harness op core.svc.key.create --json '{"name": "n8n", "roles": ["member"], "days": 90, "cidrs": ["203.0.113.0/24"]}'