Appeler Grace depuis un hook

Créer une clé API de projet et l'utiliser dans un hook d'agent, un script CI ou une automatisation locale.

Les agents de code permettent d'exécuter des hooks à différents moments : avant le démarrage, avant ou après un appel d'outil, à la fin d'une tâche. Ces scripts sont headless — pas de navigateur, donc pas de flux OAuth possible.

Une clé API de projet leur donne un moyen d'appeler les outils Grace avec un simple en-tête Authorization.

Créer une clé

Ouvrez votre projet → onglet Paramètres → section Clés API.
Créer une clé, puis :
- un nom qui dit son usage (« hook validate — poste de Nathan ») : c'est le seul repère dont vous disposerez plus tard, la valeur n'étant plus consultable ;
- les outils que la clé pourra appeler — cochez le strict nécessaire ;
- une expiration, facultative.
Copiez la valeur immédiatement. Elle est affichée une seule fois. Elle n'est pas stockée en clair : personne, pas même un administrateur de la plateforme, ne pourra la relire.

Perdue, une clé ne se retrouve pas — elle se révoque et se recrée.

Ce qu'une clé peut appeler

Outil	Méthode et route	À quoi ça sert dans un hook
`prepare_task`	`POST /api/prepare-task`	Préparer les conventions au début d'une tâche
`validate`	`GET /api/validation/playbook`	Obtenir le playbook d'audit avant de conclure
`record_validation`	`POST /api/validation/reports`	Enregistrer les verdicts et preuves des expertises privées
`deepen`	`GET /api/search` et `POST /api/talents/get`	Chercher un talent, ou lire le contenu de l'un d'eux
`doctor`	`GET /api/doctor`	Diagnostiquer la configuration
`catalog`	`GET /api/catalog`	Lister le catalogue
`discover`	`GET /api/discovery/playbook`	Lire la procédure de découverte
`install`	`PATCH /api/projects/:id/talents`	Modifie la sélection de talents

install et record_validation écrivent. Un hook qui ne fait que préparer une tâche ou relire un audit n'en a pas besoin. Accordez record_validation uniquement au processus chargé de persister les verdicts privés, et install uniquement à celui qui installe ou désactive des talents.

deepen couvre les deux routes de l'outil grace_deepen, qui aiguille sur ses paramètres : { uri } lit un fichier de talent, { query } en cherche un. Un seul scope les accorde donc ensemble — il n'est pas possible d'autoriser la lecture sans la recherche.

Aucun autre en-tête n'est nécessaire : la clé désigne son projet. Si vous envoyez malgré tout un x-grace-project, il est ignoré — une clé ne peut pas être redirigée vers un autre projet.

Appeler

curl -s -X POST https://<votre-domaine>/api/prepare-task \
  -H "Authorization: Bearer $GRACE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"talentIds":["grace.architecture.hexagonal"],"language":"typescript"}'

Exemple — hook de fin de tâche qui appelle `validate`

Conservez le resolutionId renvoyé au début de la tâche, puis transmettez-le au playbook :

#!/usr/bin/env bash
set -euo pipefail

: "${GRACE_KEY:?clé API absente}"
: "${GRACE_URL:?URL Grace absente}"
: "${GRACE_RESOLUTION_ID:?resolutionId absent}"

# Rien de modifié : rien à auditer.
[ -z "$(git diff --name-only HEAD)" ] && exit 0

curl -sS --get "$GRACE_URL/api/validation/playbook" \
  -H "Authorization: Bearer $GRACE_KEY" \
  --data-urlencode "resolutionId=$GRACE_RESOLUTION_ID"

Si le playbook contient des expertises privées, le processus qui possède le scope record_validation envoie ensuite un submissionId stable et un verdict motivé pour chacune à POST /api/validation/reports. Une clé portant uniquement validate reçoit 403 insufficient_scope sur cette route.

Exemple — hook de début de tâche qui appelle `prepare_task`

#!/usr/bin/env bash
# Injecte les conventions du projet dans le contexte de l'agent, avant qu'il écrive du code.
set -euo pipefail

# Les identifiants viennent du répertoire des expertises désignables du projet
# (GET /api/prepare-task/designable).
talents="${1:?nommez au moins une expertise, séparées par des virgules}"

curl -sS -X POST "$GRACE_URL/api/prepare-task" \
  -H "Authorization: Bearer $GRACE_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg t "$talents" '{ talentIds: ($t | split(",")) }')"

Désignez tout ce que le travail touche, et conservez le resolutionId de la réponse : il fige les talents et les versions privées servis, qui sont exactement ceux que le playbook d'audit couvrira. Ce qui n'est pas désigné n'est ni servi ni relu.

Où mettre la clé

Dans une variable d'environnement, jamais dans un fichier committé. Le préfixe grc_pk_ est distinctif : il permet à un scanner de secrets (gitleaks, trufflehog) de repérer une fuite.

Poste de développement : votre profil shell, ou le gestionnaire de secrets de l'agent.
CI : les secrets du dépôt ou de l'organisation.

Comprendre les refus

Réponse	Ce qui se passe
`401 invalid_token`	Clé inconnue, révoquée, expirée — ou fonctionnalité désactivée. La réponse est volontairement la même dans les quatre cas
`403 insufficient_scope`	La clé n'autorise pas cet outil. `requiredScope` indique lequel il faut ; recréez une clé en le cochant
`403` (organisation)	L'organisation du projet n'est plus approuvée
`403 not_a_member`	Le porteur de la clé n'est plus membre de l'organisation
`404`	Le projet n'existe plus

Les droits sont réévalués à chaque appel : une clé ne fige rien. Si vous quittez l'organisation, vos clés cessent de fonctionner ; si vous y revenez, elles refonctionnent.

Révoquer

Depuis la même section, Révoquer. L'effet est immédiat : l'appel suivant est refusé.

Tout membre du projet voit les clés du projet et peut les révoquer, y compris celles créées par quelqu'un d'autre. Une clé posée dans un hook ou une CI est un fait d'exploitation du projet, pas un secret personnel — et lors d'une fuite, la révocation ne doit pas attendre le retour de son auteur.

Ce que les clés ne font pas

Gérer d'autres clés : la création et la révocation exigent une session web. Une clé fuitée ne peut pas se perpétuer.
Accéder au dashboard : une clé n'ouvre que les outils qu'elle nomme, sur son projet.
Remplacer OAuth pour un usage interactif : pour brancher un agent à Grace, utilisez l'URL MCP du projet, qui ne contient aucun secret et peut être committée.

Appeler Grace depuis un hook

On this page