Skip to main content

​
API key format

Sentrail API keys start with agk_ and are generated once — the raw key is never stored. Sentrail stores only a SHA-256 hash. 
agk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Creating a key

Keys are created through the dashboard at Settings → API Keys → New Key, or via the manage-api-keys edge function (requires an authenticated user session with admin role). When creating a key, you assign:
  • Name — human-readable label
  • Scopes — one or more of the valid scopes (see below)
  • Expiry — number of days until the key expires (default: 90)

​
Passing the key

Include the key in the Authorization header as a Bearer token on every request: 
Authorization: Bearer agk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Scopes

ScopeGrants access to
gatewaygateway-proxy — forward requests to tool APIs
evaluateevaluate-action — evaluate without forwarding
mcpmcp-gate — MCP tool gating (falls back to evaluate)
A key must include the required scope for the endpoint being called. If the scope is missing, the endpoint returns 401.

​
Key lifecycle

Keys are checked on every request:
  1. The raw key is hashed with SHA-256
  2. The hash is looked up in api_keys
  3. If revoked = true, the key is rejected
  4. If expires_at is in the past, the key is rejected
  5. If scopes does not include the required scope, the key is rejected
  6. On success, last_used_at is updated

​
Revoking a key

Revoke a key in Settings → API Keys or via the manage-api-keys function. Revoked keys are rejected immediately on the next request.

​
Error responses

// Missing or malformed key
{ "ok": false, "error": "Invalid or expired API key" }

// Key valid but wrong scope
{ "ok": false, "error": "Invalid or expired API key" }
Both cases return HTTP 401. Sentrail does not distinguish between a missing key and a wrong-scope key to avoid leaking information.
API keys (agk_) are for agent-facing endpoints. The kill-switch, approval-decision, and manage-api-keys endpoints require a Supabase user JWT (from a logged-in dashboard session), not an agk_ key.