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.limitsavecdays) 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
adminousuperadmin. - 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"]}'