Skip to content

Authentication And Tokens

Read endpoints are generally public unless a deployment is configured otherwise. Writes and token management require authentication.

Humans

Humans authenticate through OIDC session login. The CLI supports loopback login:

benchdb auth login --server "$BENCHDB_SERVER_URL"

The login flow mints a user-owned API token only after the loopback exchange completes. The CLI stores credentials in a local credentials file with tight permissions.

The intermediate loopback code is stored server-side as a short-lived hash and is single-use. This lets cli-start and cli-exchange land on different server replicas without sticky routing, while avoiding storage of the plaintext code.

The web app exposes the same user-owned token model at /account for interactive use. It shows the current OIDC identity, supports browser logout, lists token prefixes and timestamps, creates new tokens, and revokes existing tokens. Token plaintext is shown only in the creation response.

The new system does not carry forward local password login, open registration, or general user CRUD pages. User records are created from OIDC identity during login. The supported self-service surface is /account, /api/users/me, and the user-owned API-token endpoints.

Automation

Automation should use server-minted reporter tokens:

export BENCHDB_TOKEN=<token>
benchdb results submit "bench-results/*.json" --server "$BENCHDB_SERVER_URL"

Token resolution order is:

  1. --token
  2. BENCHDB_TOKEN
  3. CLI credentials file

For CI and shared scripts, prefer exporting BENCHDB_TOKEN and omitting --token; reserve --token for explicit local overrides. That keeps tokens out of normal process arguments.

Operators can bootstrap reporter tokens directly on the server host or in an admin job with database access:

BENCHDB_DB_URL="$BENCHDB_DB_URL" benchdb admin tokens create \
  --email ci@example.com \
  --user-name "BenchDB CI Reporter" \
  --token-name buildkite

The command creates the user row if needed, writes only the token hash and prefix to Postgres, and prints the plaintext token once as JSON. Put that value in the reporter secret named BENCHDB_TOKEN.

This means a deployment can migrate CI reporters before human OIDC is fully wired up. The reporter token is still backed by a BenchDB user row so writes have an owner, but the reporter does not need a browser session or password-era login flow.

Token Management

Use the CLI for scripts and repeatable automation:

benchdb auth token list --server "$BENCHDB_SERVER_URL"
benchdb auth token revoke <token-id> --server "$BENCHDB_SERVER_URL"

The API never returns token plaintext after creation. Result submission and CI reporting should never print the token.

There is no supported admin API for listing, editing, or deleting arbitrary users in the current system. If a deployment needs operator user administration later, it should be added as a separate authenticated operator feature with explicit authorization rules.