Authentication

Dr.Gero uses two auth modes depending on the endpoint.

Dr.Gero API token

Runtime and resource APIs accept API tokens created in Settings → Tokens.

export DRGERO_TOKEN="drgero_REPLACE_WITH_TOKEN_FROM_SETTINGS"

curl -sS "$API_BASE/api/leaderboards" \
  -H "Authorization: Bearer $DRGERO_TOKEN" | jq

Supported header forms:

Authorization: Bearer drgero_...
X-API-Key: drgero_...
X-Dr.Gero-API-Key: drgero_...

Use Authorization: Bearer unless you have a reason to use an API-key header.

Push dataset token

PUSH leaderboards can also issue webhook-only tokens that start with hpd_. They can be used only for that leaderboard's dataset endpoints.

curl -sS -X POST "$API_BASE/v1/leaderboard/$PUSH_LEADERBOARD_ID/dataset/push" \
  -H "X-Dr.Gero-Push-Token: $PUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"hello","output":"world"}'

Supabase user session

Some /api/... endpoints are used by the signed-in UI and require a Supabase session access token rather than a Dr.Gero API token. These include:

• /api/tokens
• /api/invite-user
• /api/integrations/validate
• /api/leaderboards/{id}/models/auto-select

In browser code, the app obtains the session token from Supabase and sends it as Authorization: Bearer <supabase_access_token>.

Scopes

API tokens can be restricted by scopes.

Scope	Allows
leaderboards:read	List/read leaderboards, runs, traces, datasets.
leaderboards:write	Create/update/delete leaderboards, add/remove models, push rows.
leaderboards:run	Start leaderboard runs and dataset-improvement runs.
leaderboards:inference	Call inference.
models:read	List/read Dr.Gero models and base models.
models:write	Create/update/delete Dr.Gero models.
models:fine-tune	Run/sync fine-tuning.
leaderboards:*	All leaderboard scopes.
models:*	All model scopes.
*	Full API access.

Budget headers

When inference settles usage/cost, responses may include:

X-Dr.Gero-Token-Budget-Limit-Usd: unlimited
X-Dr.Gero-Token-Budget-Remaining-Usd: unlimited
X-Dr.Gero-Token-Budget-Used-Usd: 0.0003
X-Dr.Gero-Token-Budget-Reset-At: 2026-07-01T00:00:00.000Z

Use these headers to alert users before a token reaches its budget.