Skip to main content

​
Bearer tokens

Every Repo API request requires an Authorization header:
Keys start with the repo_ prefix and are issued from the console’s Developers tab. The full secret is shown once at creation time — Repo stores only a SHA-256 hash, so a lost key cannot be recovered. Mint a new one and rotate.

​
Two ways to mint keys

The bootstrapping pattern: mint your first admin key in the console, store it in your secrets manager, then use the API to issue scoped agent keys.

​
Key shape

​
Actor types

  • agent — Default. An AI agent making programmatic requests.
  • application — A traditional application or backend service.
  • admin — Capable of minting other keys (admin action grants this).
The actor type is metadata only — it doesn’t change what the key can do (that’s controlled by allowedActions). It’s there for audit + observability.

​
Actions

Every action is a discrete permission a key may carry. Pass the full set when creating a key; Repo enforces them at the route level.

​
Provider scopes

allowedProviders is an optional whitelist of provider IDs the key may retrieve from. Pass null for no restriction (the key sees everything the org has connected); pass an array to scope it down.
Available providers: slack, google_drive, notion, gmail. When /v1/search or /v1/context runs against a key with provider scopes, hits from excluded providers are filtered out server-side before any data leaves Repo — the key cannot bypass the scope by inspecting the response.

​
Rate limits

Each (api_key, action) pair has a per-minute budget — default 60 req/min, configurable per-deployment via API_RATE_LIMIT_PER_MIN. Over-limit calls return 429 with headers:
See Rate limits for tier-specific budgets and burst behavior.

​
Revocation

Revoked keys take effect immediately (no cache). The revoke endpoint refuses to delete the key currently authenticating the request — you can’t lock yourself out by accident.

​
Console keys vs. API keys

The console uses Supabase Auth tokens (the Authorization: Bearer eyJ... from a logged-in human). API keys are for agents. Repo treats them as different actor types in the audit log so you can always distinguish “Gabriel did X” from “the support agent did X”. Console endpoints are namespaced under /v1/console/* and never accept API keys. Agent endpoints are namespaced under /v1/* (no console prefix) and only accept API keys.