Authentication

Every /api/v1 request authenticates with an API key passed as a bearer token:

Authorization: Bearer vlr_live_...

Keys look like vlr_live_ followed by a random secret. Valara stores only a hash of the key plus a short display prefix, so the full secret is shown to you exactly once when the key is created. Treat it like a password.

Creating a key

Once you have an account, you provision keys yourself:

1. Open Settings → API Keys in the dashboard.
2. Name the key for where it runs (e.g. "CI pipeline") and choose its scopes.
3. Copy the full secret. It is shown once; store it before you leave the page.

Key management is session-authenticated (the dashboard, or the CLI's device session). An API key cannot create or revoke keys, so a leaked key can never mint new ones or escalate its own scopes. The same actions are available programmatically with a session credential at POST / GET /api/v1/keys and DELETE /api/v1/keys/{id}.

Scopes

Each key carries a set of scopes. A request that needs a scope the key lacks is rejected with 403 forbidden before any work happens (so a read-only key can never start a billable review).

How a request is resolved

1. A Authorization: Bearer vlr_live_… header is verified against your key.
2. The key resolves to the owning Valara user; reviews, credits, and history are scoped to that user.
3. The required scope for the endpoint is enforced.

Browser sessions (the Valara web app) authenticate with cookies and carry full access. API keys are the path for machines, agents, and CI.

Failure modes

Both use the standard error envelope. Credits remain the hard financial ceiling: a review that would exceed your balance returns 402 insufficient_credits rather than running.