Web Search BYOK

Bring Your Own Key (BYOK) lets you use your own search provider credentials when using Online Search (@online). Successful BYOK searches are not billed by Routeway for search usage — you pay the provider directly.

BYOK only affects search billing. Chat model token costs still apply as usual.

Platform search vs BYOK

By default, Routeway handles search for you when you append @online to a model ID. Daily limits and optional overage billing apply — see Server Tools pricing. With BYOK, Routeway calls your chosen provider (Tavily, Exa, or Valyu) using credentials you supply. When BYOK is used successfully, Routeway does not charge for that search.

Search path	Routeway daily limit	Routeway search charge
BYOK (Tavily, Exa, or Valyu)	Not counted	$0
Platform search (default)	Yes	Free tier included; paid overage after daily cap

If BYOK is attempted but fails (invalid key, provider error, etc.), Routeway falls back to platform search. Standard platform search limits and billing apply for that search. Up to 3 search rounds can run per chat request when the model needs multiple lookups.

Supported providers

Provider	Value	Notes
Tavily	`tavily`	Keys often start with `tvly-`
Exa	`exa`
Valyu	`valyu`

You can save one key per provider per account. Get API keys from your provider’s dashboard:

Quick start

Open Dashboard → Settings and scroll to Web Search Keys.
Add a key for Tavily, Exa, or Valyu.
Enable Prefer BYOK so saved keys are used automatically on @online requests.

Then use @online as usual — no extra headers needed:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.routeway.ai/v1",
    api_key=os.getenv("ROUTEWAY_API_KEY"),
)

response = client.chat.completions.create(
    model="gpt-4o@online",
    messages=[{"role": "user", "content": "What happened in AI this week?"}],
)

How search is chosen

Resolution order (highest priority first):

Per-request key — X-Web-Search-API-Key (+ optional X-Web-Search-Provider)
Saved key — only when Prefer BYOK is enabled in Settings, or via the X-Prefer-Web-Search-BYOK header
Platform search — default fallback

Per-request headers

For integrations that need to pass a key on each request (for example, multi-tenant apps), add these headers to POST /v1/chat/completions alongside your normal Routeway auth.

Header	Required	Values	Purpose
`X-Web-Search-API-Key`	For one-off BYOK	Provider API key	Use this key for search on this request only. Not stored.
`X-Web-Search-Provider`	Recommended with request key	`tavily`, `exa`, `valyu`	Which provider to call.
`X-Prefer-Web-Search-BYOK`	Optional	`true` / `false`	Override the Prefer BYOK dashboard setting for this request.

Behavior details:

X-Web-Search-API-Key present → BYOK is used for that request. Prefer BYOK does not need to be enabled.
X-Web-Search-Provider omitted with a request key → Tavily is assumed; keys starting with tvly- are inferred as Tavily.
X-Web-Search-Provider only (no API key) → selects which saved key to use, but only if Prefer BYOK is enabled (in Settings or via header).
Headers are case-insensitive (x-web-search-api-key works).

If multiple providers are saved and no X-Web-Search-Provider is set, priority is: tavily → exa → valyu.

Example: one-off Tavily key

cURL
Python

curl https://api.routeway.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEWAY_API_KEY" \
  -H "X-Web-Search-API-Key: tvly-your-tavily-key" \
  -H "X-Web-Search-Provider: tavily" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o@online",
    "messages": [
      {"role": "user", "content": "What happened in AI this week?"}
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.routeway.ai/v1",
    api_key=os.getenv("ROUTEWAY_API_KEY"),
    default_headers={
        "X-Web-Search-API-Key": os.getenv("TAVILY_API_KEY"),
        "X-Web-Search-Provider": "tavily",
    },
)

response = client.chat.completions.create(
    model="gpt-4o@online",
    messages=[{"role": "user", "content": "What happened in AI this week?"}],
)

Per-request keys are ideal for multi-tenant apps where each end user has their own search provider key. Keys sent in headers are never stored on Routeway’s servers.

Typical setups

Dashboard — save key, always BYOK

Add your provider key under Settings → Web Search Keys
Enable Prefer BYOK
Call chat with model: "...@online" — no extra headers needed

Server integration — key per request

Send X-Web-Search-API-Key (+ X-Web-Search-Provider) on each @online chat request. Good for multi-tenant apps where each end user has their own search key.

Default platform search — no BYOK

Use @online with no BYOK headers and Prefer BYOK turned off. Routeway handles search; normal daily limits and overage apply. See Server Tools.

Security

Routeway treats search provider keys as sensitive credentials. Here’s how they’re handled:

Encrypted at rest

Keys saved in the dashboard are encrypted before storage and are never stored in plain text. They are decrypted only in memory when required to perform a search request and are not logged in plaintext.

Masked after save

After you add a key, only the last four characters are shown in the dashboard. The full value cannot be retrieved later.

Separate from API keys

Search provider keys are stored independently from your Routeway sk- API keys.

Per-request keys aren't stored

Keys sent via X-Web-Search-API-Key are used only for that request and are not saved to your account.

Routeway does not log or cache decrypted search provider keys. Keys are decrypted only when needed to make a search request to your chosen provider.

Best practices

Use the dashboard or headers — save keys in Settings → Web Search Keys, or pass them via X-Web-Search-API-Key. Never include provider keys in chat messages, prompts, or model strings.
Use environment variables — load keys from a secrets manager or environment variables in your application, not hardcoded in source code.
Rotate if exposed — if a key may have been leaked, update it immediately in the dashboard. The old key is replaced as soon as you save a new one.
Scope keys at the provider — create separate search API keys per environment (production, staging) in your provider’s dashboard when possible.

FAQ

Do I still pay for chat tokens when using BYOK?

Yes. BYOK only affects search billing. Model input and output tokens are billed at the usual rates for your chosen model.

What happens if my BYOK key fails?

Routeway falls back to platform search for that request. Standard platform search limits and billing apply for the fallback search.

Can I save keys for multiple providers?

Yes — one key per provider in Settings → Web Search Keys. If multiple are saved and no X-Web-Search-Provider is set, Routeway tries them in order: tavily → exa → valyu.

Where should I put my provider API key?

Save keys in the dashboard under Web Search Keys, or pass them per request via the X-Web-Search-API-Key header. Do not put provider keys in the chat message body or model string.

How do I rotate a saved key?

Open Dashboard → Settings, scroll to Web Search Keys, and update the key for your provider. The old key is replaced immediately.

Is it safe to save my search provider key in Routeway?

Yes. Saved keys are encrypted at rest and only decrypted when needed to perform a search. The full key is never shown again after you save it — only a short hint (last four characters) is displayed in the dashboard. Routeway does not log decrypted keys.

Get Started

Platform Details

Help & Resources

Core Concepts

Account Management

Guides

Platform search vs BYOK

Supported providers

Quick start

How search is chosen

Per-request headers

Example: one-off Tavily key

Typical setups

Dashboard — save key, always BYOK

Server integration — key per request

Default platform search — no BYOK

Security

Encrypted at rest

Masked after save

Separate from API keys

Per-request keys aren't stored

Best practices

FAQ

​Platform search vs BYOK

​Supported providers

​Quick start

​How search is chosen

​Per-request headers

​Example: one-off Tavily key

​Typical setups

Dashboard — save key, always BYOK

Server integration — key per request

Default platform search — no BYOK

​Security

Encrypted at rest

Masked after save

Separate from API keys

Per-request keys aren't stored

​Best practices

​FAQ

Platform search vs BYOK

Supported providers

Quick start

How search is chosen

Per-request headers

Example: one-off Tavily key

Typical setups

Security

Best practices

FAQ