Authentication

Verial exposes two HTTP surfaces with different auth flows.

Internal API (`/`)

Every internal API request authenticates with an organization API key as a Bearer token. Keys are prefixed vk_.

curl https://api.verial.ai/environments \
  -H "Authorization: Bearer vk_xxx"

Creating keys

Go to Settings > API Keys in the Verial dashboard.
Click Create Key.
Copy the key immediately. It is not shown again.

Keys inherit the permissions of the organization that created them and can only access resources inside that organization.

SDK

import Verial from "@verial-ai/sdk";

const verial = new Verial({
  apiKey: process.env.VERIAL_API_KEY,
});

Public v1 API (`/v1`)

The v1 API is how external agents run published benchmarks. It uses two token types.

1. Solver key (`vrl_slv_`)

Bearer token tied to a Solver, a per-organization agent identity. Minted from the dashboard under Solvers (or via the internal API) and works across any benchmark your organization is allowed to run, including any benchmark with visibility=Public. Authenticates only the create-run call:

curl -X POST https://api.verial.ai/v1/benchmark-runs \
  -H "Authorization: Bearer vrl_slv_xxx" \
  -H "Content-Type: application/json" \
  -d '{"benchmark": "fax-referral@1", "scored": false}'

The response includes a per-run bearer token (bearer_token field) and task-run URLs.

2. Run bearer token (`vrl_run_`)

Short-lived Bearer token returned from POST /v1/benchmark-runs. Authenticates all subsequent per-run calls for that benchmark run:

GET /v1/benchmark-runs/{id}
ALL /v1/benchmark-runs/{id}/{fhir,hl7,files,portal}/*
POST /v1/task-runs/{id}/start
POST /v1/task-runs/{id}/complete

curl "https://api.verial.ai/v1/benchmark-runs/$BENCHMARK_RUN_ID/files/inbox" \
  -H "Authorization: Bearer vrl_run_xxx"

The run bearer token expires (bearer_token_expires_at in the create response). Save it on run creation, discard after the run completes.

Security Best Practices

Store keys in environment variables, not in source code.
Rotate keys periodically; revoke compromised keys via the dashboard.
Use separate keys for dev and prod.
Never put vk_, vrl_slv_, or vrl_run_ tokens into front-end code or logs.

Error Responses

Missing or invalid credentials return 401 Unauthorized:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

A Solver key used against a private benchmark in another organization returns 404 Not Found. Public benchmarks are runnable from any organization’s Solver key.

​Internal API (/)

​Creating keys

​SDK

​Public v1 API (/v1)

​1. Solver key (vrl_slv_)

​2. Run bearer token (vrl_run_)

​Security Best Practices

​Error Responses