Call Grace from a hook

AI agents can run hooks at different points: before startup, before or after a tool call, or at the end of a task. These scripts are headless — no browser, so an OAuth flow is not possible.

A project API key gives them a way to call Grace tools with a simple Authorization header.

Create a key

1. Open your project → Settings tab → API keys section.
2. Choose Create a key, then set:
   • a name that states its use ("hook validate — workstation"): it is the only way to identify the key later, because you will not be able to see its value again;
   • the tools the key may call — select only what is needed;
   • an optional expiration.
3. Copy the value immediately. It is shown only once. It is not stored in plain text: nobody, not even a platform administrator, can retrieve it.

You cannot recover a lost key — revoke it and create a new one.

What a key can call

No other header is necessary: the key identifies its project. If you nevertheless send x-grace-project, it is ignored — a key cannot be redirected to another project.

Call Grace

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

Example — end-of-task hook calling validate

Keep the resolutionId returned at the start of the task, then pass it to the playbook:

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

: "${GRACE_KEY:?Missing API key}"
: "${GRACE_URL:?Missing Grace URL}"
: "${GRACE_RESOLUTION_ID:?Missing resolutionId}"

# Fetch the playbook even when the working tree is clean: the sealed review may cover committed or untracked changes.

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

The process with the record_validation scope then sends a stable submissionId, verdicts for reviewable Grace rules, and verdicts for Custom Talents to POST /api/validation/reports. A key with only validate receives 403 insufficient_scope on this route.

Record the first exhaustive report before correcting a blocking violation. After correction and a new review, send a second report with a new submissionId. Reuse the first identifier only to retry the exact same report.

Example — start-of-task hook calling prepare_task

#!/usr/bin/env bash
# Load project conventions into the agent's context before it writes code.
set -euo pipefail

# Get these IDs from the project's designable talent directory
# (GET /api/prepare-task/designable).
talents="${1:?Specify at least one talent, separated by commas}"

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(",")) }')"

Where to put the key

In an environment variable, never in a committed file. The grc_pk_ prefix is distinctive: it lets a secret scanner (gitleaks, trufflehog) spot a leak.

• Development workstation: your shell profile or the agent's secrets manager.
• CI: repository or organization secrets.

Understand denied requests

Permissions are re-evaluated on every call: a key does not lock them in. If you leave the organization, your keys stop working; if you rejoin, they work again.

Revoke a key

In the same section, choose Revoke. It takes effect immediately: the next call is denied.

Any project member can see and revoke project keys, including those created by someone else. A key used in a hook or CI is part of the project's operations, not a personal secret — and if it leaks, revocation must not wait for its creator to return.

What keys cannot do

• Manage other keys: creation and revocation require a web session. A leaked key cannot perpetuate itself.
• Access the dashboard: a key opens only its named tools on its project.
• Replace OAuth for interactive use: to connect an agent to Grace, use the project's MCP URL, which contains no secret and can be committed.