Authentication

Every request authenticates with an API key passed as a Bearer token. One key works for everything: inference, and the whole management API (logs, judges, evals, training, dedicated endpoints, aliases), unless you narrow it with scopes at creation.

Creating a key

Open the dashboard → API keys.
Click Create key, give it a name, choose its scopes (all ticked = unrestricted), and copy the value.

Your key is shown once, at creation — errorbar stores only a hash and can’t show it to you again. If you lose it, revoke it and create a new one.

Every key belongs to a workspace. All usage, billing, and resources created with a key are scoped to that workspace.

Using a key

Send it in the Authorization header as a Bearer token:

Authorization: Bearer sk_sovereign_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

With the OpenAI SDK, set it as the api_key:

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.errorbar.ai/v1",
    api_key="sk_sovereign_...",
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.errorbar.ai/v1",
  apiKey: process.env.ERRORBAR_API_KEY,
});

Key format and failures

All errorbar keys start with sk_sovereign_. A missing, malformed, or revoked key returns 401 with the standard envelope, so one parser handles auth failures and every other refusal:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

The cheapest way to verify a key works, and see which workspace it lands in, is GET /v1/setup/status: a 200 proves the key is live and reports where your workspace is in the setup, including what to do next. Send Accept: text/plain for flat key=value lines if you’re parsing from a shell script.

Key permissions and roles

A key is not just a workspace pointer. Every key acts as the user who minted it, and permission checks run against that user’s workspace role per operation:

Read endpoints work with any workspace key. (The training surfaces: GRPO, RAFT rounds, environment tools, and model versions, are the exception: they require owner/admin even to read.)
Endpoints that spend money or redirect traffic require the minting user to be a workspace owner or admin, and return 403 otherwise: creating dedicated endpoints, fine-tuning jobs, GRPO runs, eval runs, datasets, labels, judges and anything that judges (calibration, scans, suggestions, auto-improve), and alias repoints.

The practical consequence: a key minted by a regular member is a safe read-and-infer credential, and revoking a person’s admin role also downgrades what their existing keys can do. Mint CI keys from an admin account deliberately, not by accident. Money-creating endpoints additionally carry a per-workspace abuse guard (default 20 requests per 60 seconds); past it you get 429 with a Retry-After header.

Key scopes

Roles say what the person may do; scopes narrow what one key may do on the management API, so the token a CI job uses to read a gate verdict is not also a token that can repoint production. Scopes are checked on every /v1 management call, before the role check, and a call that fails the scope check never reaches the service.

Scope	Covers
`read`	Every `GET`: runs, gates, evidence bundles, logs, traces, criteria, aliases, jobs, audit exports, reward sessions and the anchor report. `POST /v1/verify` also counts as read: it checks a signature and writes nothing.
`evals:write`	Writes under `/v1/evals`, `/v1/criteria`, `/v1/labels`, `/v1/label_sets`, `/v1/datasets`, `/v1/logs` and `/v1/traces`: create and cancel eval runs; create, align, scan and edit criteria; write grades, golden sets and pair labels; build datasets from logs; import logs.
`aliases:write`	Writes under `/v1/aliases`: create, repoint and delete model aliases — the one write that changes what production serves.
`platform:write`	Every other write: fine-tuning jobs and files, GRPO and RAFT runs, model-version adoption, dedicated endpoints, batches, environment tools, registered eval endpoints, judge settings, reward sessions and anchor checks.

The scope a call needs is derived from the request itself (method plus the first path segment after /v1), never declared per route, so a new write surface is protected the day it exists: any write path not listed above falls to platform:write. How a key gets its scopes:

Pick them in the Create key dialog on the dashboard’s API keys page. Every scope starts ticked; untick to narrow. read cannot be unticked, because any scope implies read: a key that may write evals may read them. The CI-gate key is Read alone.
Keys minted before scopes existed carry no scope list and keep full access; the key table shows them as full access. Nothing already wired changes.
Scopes are fixed at creation. To narrow a key, mint a new one and revoke the old.
Inference through the gateway is a different surface and ignores scopes: a read-only key still serves chat completions.

A call outside the key’s scopes returns 403 with code insufficient_scope and names the scope it needed:

{
  "error": {
    "message": "This API key does not have the \"aliases:write\" scope. Mint a key with it under Settings → API keys, or use a key with full access.",
    "type": "permission_error",
    "code": "insufficient_scope",
    "required_scope": "aliases:write"
  }
}

Scopes and roles compose: a platform:write key minted by a regular member still gets 403 (insufficient_permissions) on the owner/admin endpoints, because the key never outranks the person who minted it.

Revoking a key

Revoke any time from the dashboard. Revocation is checked on every request, so it takes effect immediately: there is no cached session to wait out. Each key’s last-used time is tracked, which makes stale keys easy to spot before you rotate.

Provider keys for bring your own key are a separate thing: they are stored encrypted and write-only, and never work as errorbar API keys.

Best practices

Never commit keys to source control

Load keys from environment variables or a secrets manager. A key in a public repo should be treated as compromised: revoke it.

Use separate keys per environment

Create distinct keys for development, staging, and production so you can revoke one without affecting the others, and attribute usage clearly. The per-key table in Observability shows exactly which key is doing what.

Rotate periodically

Create a new key, roll your services over to it, then revoke the old one. Last-used timestamps confirm the old key has gone quiet before you revoke.

Get started

Capture

Observe

Grade & Judge

Evaluate

Improve

Run at scale

Platform

Creating a key

Using a key

Key format and failures

Key permissions and roles

Key scopes

Revoking a key

Best practices

​Creating a key

​Using a key

​Key format and failures

​Key permissions and roles

​Key scopes

​Revoking a key

​Best practices

Creating a key

Using a key

Key format and failures

Key permissions and roles

Key scopes

Revoking a key

Best practices