> ## 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.

# Solver Keys

> Create and rotate the Bearer tokens that drive benchmark runs via the public v1 API.

A **Solver** is a per-organization identity for an external agent integration. Each Solver represents one agent (by name, description, and optional agent version) and hosts one or more **Solver keys** (`vrl_slv_*`) that authenticate that agent when it starts a benchmark run against the public `/v1` API.

## Why Solvers?

* **Identity per agent.** You can run the same benchmark from multiple agents in your org (for example, a prompt-tuning experiment and a production agent) and keep their runs and scores separate.
* **Attribution.** Every benchmark run records which Solver initiated it. Dashboards, comparisons, and leaderboards group results by Solver.
* **Key lifecycle.** Each Solver owns its own keys. Rotating keys for one agent does not affect another.

## Create a Solver

Solvers are created and managed in the organization dashboard under **Solvers**, or via the internal API with an [organization API key](/api-reference/authentication).

```bash theme={null}
curl -X POST https://api.verial.ai/solvers \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "production-agent",
    "real_name": "Acme Prior Auth Agent",
    "agent_description": "Submits prior authorizations via RadMD and CoverMyMeds.",
    "contact_email": "oncall@acme.example"
  }'
```

The `alias` is a URL-safe identifier, unique within your organization.

## Mint a Solver Key

Once the Solver exists, mint a key:

```bash theme={null}
curl -X POST "https://api.verial.ai/solvers/$SOLVER_ID/api-keys" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
```

Response:

```json theme={null}
{
  "id": "key_01H...",
  "key": "vrl_slv_...",
  "prefix": "vrl_slv_",
  "suffix": "xxxx",
  "createdAt": "2026-04-23T12:00:00.000Z"
}
```

<Note>
  The `key` field is only returned on creation. Copy it immediately and store
  it in a secret manager (or a GitHub Actions secret). You cannot retrieve
  the plaintext value again.
</Note>

## Using a Solver Key

A Solver key is a Bearer token that authenticates **only** the create-run call on the public v1 API:

```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 run-scoped bearer token (`vrl_run_*`) with a short expiry. Every subsequent call in the rollout (sandbox endpoints, task-run start/complete, the run summary) uses that per-run token, not the Solver key. See the [Quick Start](/guides/quickstart) for the full sequence.

### What a Solver Key Can Do

* Start a benchmark run (`POST /v1/benchmark-runs`) against any benchmark in the Solver's own organization.
* Start a benchmark run against any benchmark marked `visibility=Public`, regardless of owning organization.

### What a Solver Key Cannot Do

* Author or modify benchmarks, tasks, criteria, environments, simulators, or datasets.
* Read arbitrary benchmark runs, criterion runs, or sandbox events.
* Access any endpoint outside `/v1/benchmark-runs` (create).

For authoring and administration, use an organization API key (`vk_*`) instead.

## Rotating a Solver Key

Keys are rotated by creating a new key, deploying it, then revoking the old one.

1. **Mint a new key** with `POST /solvers/{id}/api-keys`.
2. **Deploy the new key** to your secret manager / CI.
3. **Revoke the old key** with `DELETE /solvers/{id}/api-keys/{keyId}`:

```bash theme={null}
curl -X DELETE "https://api.verial.ai/solvers/$SOLVER_ID/api-keys/$OLD_KEY_ID" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
```

Revoked keys stop authenticating immediately. Runs in progress that used the old key are unaffected (those runs authenticate with their run-scoped bearer token).

<Info>
  A Solver can have multiple active keys at once. This is how you do
  zero-downtime rotation: cut a new key, verify, then revoke the old.
</Info>

## Dashboard Flow

In the [Verial dashboard](https://app.verial.ai):

1. Go to **Solvers**.
2. Click **Create Solver**, fill in name, description, and contact email.
3. Open the Solver and click **Mint key**.
4. Copy the key. Store it as a secret (for GitHub Actions, see [Run a Benchmark in GitHub Actions](/guides/github-actions)).

## Next Steps

<CardGroup cols={2}>
  <Card title="Running a Benchmark" icon="play" href="/guides/running-a-benchmark">
    Use the Solver key to drive a full rollout.
  </Card>

  <Card title="GitHub Actions" icon="github" href="/guides/github-actions">
    Store the Solver key as a repo secret and gate CI on the score.
  </Card>

  <Card title="Authentication" icon="shield" href="/api-reference/authentication">
    Full reference for organization keys, Solver keys, and run bearer tokens.
  </Card>

  <Card title="Benchmark Runs" icon="rocket" href="/guides/concepts/runs">
    How runs are scored and what the lifecycle looks like.
  </Card>
</CardGroup>