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.

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:

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:

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.

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