BYOK (Bring Your Own Key)

BYOK Header Integration Guide

Overview

BYOK (Bring Your Own Key) allows you to use your own model provider credentials in an API request. UURoute still uses your platform API key for authentication, model access control, quota enforcement, and billing records. The provider credentials you submit are used only for the current request and are never stored or reused.

Each BYOK request must include:

Authorization: Bearer <UUROUTE_API_KEY>: Your UURoute platform API key.
X-UURouter-BYOK-Provider: The provider used for this request.
Either X-UURouter-BYOK-API-Keys or X-UURouter-BYOK-Credentials: Your provider credentials.

Do not put provider credentials in provider-native headers such as x-api-key, x-goog-api-key, or api-key.

Supported Providers

X-UURouter-BYOK-Provider currently supports the following values:

Provider value	Provider	Credential header
`aistudio`	Google AI Studio	`X-UURouter-BYOK-API-Keys`
`vertex`	Google Vertex AI	`X-UURouter-BYOK-Credentials`
`aws-bedrock`	AWS Bedrock	`X-UURouter-BYOK-Credentials`
`anthropic`	Anthropic	`X-UURouter-BYOK-API-Keys`
`openai`	OpenAI	`X-UURouter-BYOK-API-Keys`

The Provider value must exactly match the value in the table. For example, use aistudio for Google AI Studio and aws-bedrock for AWS Bedrock.

Common Headers

Header	Required	Description
`Authorization`	Yes	Your UURoute platform API key in the format `Bearer <UUROUTE_API_KEY>`.
`X-UURouter-BYOK-Provider`	Yes	The provider identifier. It must be one of the values in the “Supported Providers” table.
`X-UURouter-BYOK-API-Keys`	One of two	Used for OpenAI, Anthropic, and Google AI Studio. Supports up to three API keys.
`X-UURouter-BYOK-Credentials`	One of two	Used for Google Vertex AI and AWS Bedrock. Supports up to three credential JSON objects encoded as unpadded base64url strings.
`X-UURouter-BYOK-Fallback`	No	Whether to use platform Credits if the BYOK attempt fails. Accepts `true` or `false`; the default is `false`.

Provide either X-UURouter-BYOK-API-Keys or X-UURouter-BYOK-Credentials. If both are provided and the API key header is not empty, the system gives priority to X-UURouter-BYOK-API-Keys.

To provide multiple API keys, separate them with commas:

X-UURouter-BYOK-API-Keys: <key_1>,<key_2>,<key_3>

Pricing

BYOK requests use your provider account, so the provider charges are billed directly between you and the corresponding provider.

UURoute charges a BYOK service fee equal to 3% of the standard platform price. For example, if the same request would cost $1 using platform Credits, UURoute charges a $0.03 BYOK service fee. The actual model usage charge is billed to your provider account.

If a request falls back to platform Credits, it is billed at the standard platform Credits rate, and the BYOK service fee does not apply.

BYOK Provider Examples

OpenAI

Use openai as the Provider value. Pass your OpenAI API key in X-UURouter-BYOK-API-Keys.

curl 'https://api.uuroute.ai/v1/chat/completions' \
  -H 'Authorization: Bearer <UUROUTE_API_KEY>' \
  -H 'X-UURouter-BYOK-Provider: openai' \
  -H 'X-UURouter-BYOK-API-Keys: <OPENAI_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.6-luna",
    "max_completion_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hi"
      }
    ]
  }'

Anthropic

Use anthropic as the Provider value. Pass your Anthropic API key in X-UURouter-BYOK-API-Keys.

curl 'https://api.uuroute.ai/v1/messages' \
  -H 'Authorization: Bearer <UUROUTE_API_KEY>' \
  -H 'X-UURouter-BYOK-Provider: anthropic' \
  -H 'X-UURouter-BYOK-API-Keys: <ANTHROPIC_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Hi"
          }
        ]
      }
    ]
  }'

Google AI Studio

Use aistudio as the Provider value. Pass your Google AI Studio Gemini API key in X-UURouter-BYOK-API-Keys.

curl 'https://api.uuroute.ai/v1beta/models/gemini-3.7-flash:generateContent' \
  -H 'Authorization: Bearer <UUROUTE_API_KEY>' \
  -H 'X-UURouter-BYOK-Provider: aistudio' \
  -H 'X-UURouter-BYOK-API-Keys: <GOOGLE_AI_STUDIO_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Hi"
          }
        ]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 1024
    }
  }'

Google Vertex AI

Use vertex as the Provider value. Vertex AI uses GCP service account credentials. First, prepare the following JSON object:

{
  "service_account_json": {
    "type": "service_account",
    "project_id": "your-gcp-project",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
    "client_email": "xxx@your-gcp-project.iam.gserviceaccount.com",
    "token_uri": "https://oauth2.googleapis.com/token"
  },
  "project_id": "your-gcp-project",
  "location": "us-central1"
}

Encode the entire JSON object as an unpadded base64url string, then pass it in X-UURouter-BYOK-Credentials:

curl 'https://api.uuroute.ai/v1beta/models/gemini-3.7-flash:generateContent' \
  -H 'Authorization: Bearer <UUROUTE_API_KEY>' \
  -H 'X-UURouter-BYOK-Provider: vertex' \
  -H 'X-UURouter-BYOK-Credentials: <BASE64URL_VERTEX_CREDENTIALS>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Why is the sky blue?"
          }
        ]
      }
    ]
  }'

AWS Bedrock

Use aws-bedrock as the Provider value. You only need to provide your AWS credentials and Region; you do not need to specify a Bedrock Base URL.

First, prepare the following JSON object:

{
  "access_key_id": "AKIA...",
  "secret_access_key": "...",
  "region": "us-east-1",
  "session_token": "optional-session-token"
}

session_token is optional and is needed only when you use temporary AWS credentials. Encode the entire JSON object as an unpadded base64url string, then pass it in X-UURouter-BYOK-Credentials:

curl 'https://api.uuroute.ai/v1/messages' \
  -H 'Authorization: Bearer <UUROUTE_API_KEY>' \
  -H 'X-UURouter-BYOK-Provider: aws-bedrock' \
  -H 'X-UURouter-BYOK-Credentials: <BASE64URL_AWS_CREDENTIALS>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Hi"
          }
        ]
      }
    ]
  }'

Encoding Credentials

X-UURouter-BYOK-Credentials must use URL-safe Base64 encoding with the = padding removed:

printf '%s' '<credential_json>' | base64 | tr '+/' '-_' | tr -d '=\n'

Important:

Do not send raw JSON.
Do not send padded Base64 containing = characters.
Do not put multiple credentials into a JSON array and encode the array as a whole.
To provide multiple credentials, encode each credential separately, then separate the encoded values with commas or repeat the same header.

Fallback

Fallback is disabled by default. To allow UURoute to try platform Credits after the BYOK credentials fail, include:

X-UURouter-BYOK-Fallback: true

Fallback can occur only when no content has been returned to the client and the request can be retried safely. UURoute will not switch to platform Credits after response headers, response body content, or an SSE chunk has already been sent.