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

# keys.yaml

> Managing proxy upstream credential fleets and client access control.

The `keys.yaml` file is the central vault for Open Next Router. It manages both the pool of API keys you hold with upstream LLM providers, and the access tokens you issue to your clients.

## Upstream Provider Keys

These are the credentials you use to authenticate with external services like OpenAI or Anthropic.

ONR groups credentials by provider, allowing it to load-balance across multiple keys automatically within a single provider namespace.

```yaml theme={null}
providers:
  openai:
    keys:
      - name: "key-billing-a"
        value: "sk-proj-prod..."
        # (Optional) You can redirect a specific proxy key to an alternate base url
        # base_url_override: "https://my-openai-azure-proxy.com"
        
  anthropic:
    keys:
      - name: "haiku-cluster"
        value: "sk-ant-... "

  vertex:
    keys:
      - name: "vertex-sa"
        # GCP Vertex AI uses a service account JSON file instead of an API key.
        credential_file: "/etc/onr/gcp/vertex-sa.json"
        location: "global"
        # Use this explicitly for regional Vertex endpoints.
        # base_url_override: "https://us-central1-aiplatform.googleapis.com"
```

To avoid committing sensitive keys to version control, **providing an empty value allows environment variables to fulfill them.**

### Environment Override (Recommended)

ONR automatically maps `keys.yaml` entries to environment variables.

* Using a named key: `ONR_UPSTREAM_KEY_<PROVIDER>_<NAME>`
* E.g., `ONR_UPSTREAM_KEY_ANTHROPIC_HAIKU_CLUSTER=sk-ant-1234 onr run -c onr.yaml`

### Vertex AI Service Account Files

For Vertex AI, a provider key can omit `value` and use a local Google service account JSON file:

```yaml theme={null}
providers:
  vertex:
    keys:
      - name: "vertex-sa"
        credential_file: "/etc/onr/gcp/vertex-sa.json"
        location: "us-central1"
        base_url_override: "https://us-central1-aiplatform.googleapis.com"
```

* `credential_file` points to a Google service account JSON file. Keep this file readable only by the ONR runtime user, for example `chmod 600 /etc/onr/gcp/vertex-sa.json`.
* `location` is exposed to DSL expressions as `$channel.location` and defaults to `global` when `credential_file` is set.
* `base_url_override` is optional, but should be set when you want a regional Vertex host such as `https://us-central1-aiplatform.googleapis.com`.

***

## Encrypted Upstream Keys

To store credentials directly in GitHub without exposing them, you can employ built-in AES-256-GCM encryption.

You can encrypt an API key using the ONR Admin CLI:

```bash theme={null}
echo -n 'sk-xxxx' | onr-admin crypto encrypt
```

This will produce a ciphertext like `ENC[v1:aesgcm:<base64(nonce+ciphertext)>]`. Simply paste this string into `keys.yaml`.
At runtime, start the server with your symmetrical unlock key:
`ONR_MASTER_KEY=your-32-byte-secret onr run -c onr.yaml`

***

## Downstream Access Keys (Client ACL)

To control access to your ONR proxy, you issue Access Keys to your downstream clients.

```yaml theme={null}
access_keys:
  - name: "client-a"
    value: "ak-onr-client-001"
    comment: "Internal Analytics Dashboard"
```

A client provides this access token when calling ONR:
`Authorization: Bearer ak-onr-client-001`

### Environment Override (Recommended)

* Using a named key: `ONR_ACCESS_KEY_<NAME>`
* E.g., `ONR_ACCESS_KEY_CLIENT_A=ak-onr-client-001`