> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verial.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate requests to the Verial internal API and the public v1 API.

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_`.

```bash theme={null}
curl https://api.verial.ai/environments \
  -H "Authorization: Bearer vk_xxx"
```

### Creating keys

1. Go to **Settings > API Keys** in the [Verial dashboard](https://app.verial.ai).
2. Click **Create Key**.
3. 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

```typescript theme={null}
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:

```bash theme={null}
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`

```bash theme={null}
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`:

```json theme={null}
{
  "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.