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

# Auth Block

> Defining upstream authentication injection.

The `auth` block instructs ONR on how to securely pass the `$channel.key` (or dynamically generated OAuth tokens) to the upstream provider.

<Warning>
  **Never hardcode secrets inside your `.conf` files.** ONR securely pulls tokens at runtime from the active downstream session or `models.yaml`. The DSL only defines the *shape* of the injection.
</Warning>

## Standard Bearer Token

```nginx theme={null}
auth { 
  auth_bearer; 
}
```

**Effect**: Injects the HTTP header `Authorization: Bearer <channel.key>`.

## Custom Header Token

```nginx theme={null}
auth { 
  auth_header_key "x-api-key"; 
}
```

**Effect**: Injects the HTTP header `x-api-key: <channel.key>`.

## Provider OAuth Flows

If your destination provider requires real-time OAuth token exchange before making requests (such as Google Cloud Vertex AI, or specific enterprise clouds), ONR can handle the automated exchange and refresh flows for you.

```nginx theme={null}
auth {
  oauth_mode openai;  # supported: openai|gemini|qwen|claude|iflow|antigravity|kimi|google_service_account_file|custom
  auth_oauth_bearer;
}
```

* `oauth_mode` enables runtime token exchange.
* `auth_oauth_bearer` injects the resulting access token as a Bearer token.

### Google Service Account Files

Use `google_service_account_file` for Vertex AI or other Google Cloud APIs that need a signed JWT bearer assertion. The active upstream key supplies the credential file path through `keys.yaml`.

```nginx theme={null}
auth {
  oauth_mode google_service_account_file;
  oauth_scope "https://www.googleapis.com/auth/cloud-platform";
  auth_oauth_bearer;
}
```

```yaml theme={null}
providers:
  vertex:
    keys:
      - name: "vertex-sa"
        credential_file: "/etc/onr/gcp/vertex-sa.json"
        location: "global"
```

ONR reads the service account JSON, signs the assertion locally, exchanges it for a short-lived access token, caches the token, and injects `Authorization: Bearer <access-token>`.

### Custom OAuth Parameters

If using `oauth_mode custom;`, you can override any parameter from the token exchange process.

```nginx theme={null}
auth {
  oauth_token_url "https://auth.example.com/oauth/token";
  oauth_client_id "my-client";
  oauth_client_secret "my-secret";
  oauth_refresh_token $channel.key;
  
  # Define the token response parsing structure
  oauth_token_path "$.access_token";
  oauth_expires_in_path "$.expires_in";
}
```