Bring Your Own Key (BYOK)

Overview

BYOK (Bring Your Own Key) lets you store API credentials for supported upstream providers and then opt-in per request to route through your own keys. Page reading keys work differently: once saved, they are used automatically (see Page reading keys). Typical reasons to use BYOK:

Your provider bills you directly (enterprise agreements, committed-use discounts, free tiers).
You want NanoGPT routing + enhancements, without using NanoGPT platform keys.

Availability

BYOK is currently supported on:

POST /api/v1/chat/completions

Page reading keys are also used by chat in the web app, scraping on POST /api/v1/chat/completions, POST /api/scrape-urls and POST /api/v1/data/url/scrape.

Pricing

When you use BYOK:

Your provider bills you directly for usage on their side.
NanoGPT charges a 5% platform fee on top for routing and platform features.

Page reads served by your own key are free on NanoGPT; your crawler provider bills you directly. No platform fee applies to them.

Configure Keys

Web UI

Manage BYOK keys in the NanoGPT web app:

https://nano-gpt.com/byok

Keys are never shown again after saving (only a short suffix is displayed), so treat them like passwords.

API (NanoGPT key required)

API keys can list and remove saved provider keys (not OpenAI-compatible):

GET    /api/user/provider-keys
DELETE /api/user/provider-keys?provider=<provider-slug>

Adding or replacing a key and changing a ZDR declaration require the web app. If your account has a sign-in factor, sign in with an identity linked to the account and confirm it’s you. Guest accounts with no sign-in factor can continue using their session. API-key POST and PATCH requests return HTTP 403 with code owner_login_required, including restricted API keys. DELETE remains available so scripts can quickly remove a leaked provider key. Example: remove a provider key

curl -X DELETE "https://nano-gpt.com/api/user/provider-keys?provider=openai" \
  -H "Authorization: Bearer YOUR_NANOGPT_API_KEY"

Key additions, replacements, removals and ZDR declaration changes send a security notice to the account’s stored email addresses, when available.

Use BYOK On A Request

Enable BYOK

Option A: request header

x-use-byok: true

Option B: request body

{
  "byok": { "enabled": true }
}

Select a provider (optional)

If the model can route through multiple providers, you can force a specific provider. Header:

x-byok-provider: openai

Body:

{
  "byok": { "enabled": true, "provider": "openai" }
}

Fallbacks (optional)

BYOK defaults to fail-fast behavior. If your provider key fails, NanoGPT will not silently route the request through a different provider key. You can control this via the request body:

{
  "byok": { "enabled": true, "disableFallbacks": true }
}

Provider Slugs

The exact set of supported providers can evolve; the BYOK UI lists what your account can configure.

Chat / completion providers

These providers can be used for BYOK on POST /api/v1/chat/completions:

Provider	Slug	Key format
OpenAI	`openai`	API key string (`sk-...`)
OpenAI Responses	`openai-responses`	API key string (`sk-...`)
Anthropic	`anthropic`	API key string (`sk-ant-...`)
OpenRouter	`openrouter`	API key string (`or-...`)
Chutes	`chutes`	API key string (`cpk_...`)
AWS Bedrock	`aws`	JSON: `{"accessKeyId":"...","secretAccessKey":"...","region":"us-east-1"}`
Azure OpenAI	`azure`	JSON: `{"endpoint":"...","apiKey":"...","deploymentName":"...","apiVersion":"..."}`
Azure Responses	`azure-responses`	JSON: `{"endpoint":"...","apiKey":"...","apiVersion":"..."}`
Azure Anthropic Foundry	`azure-anthropic-foundry`	JSON: `{"endpoint":"...","apiKey":"..."}`
Google AI Studio	`google`	API key string (`AIza...`)
Groq	`groq`	API key string (`gsk_...`)
NVIDIA	`nvidia`	API key string (`nvapi-...`)
SambaNova	`sambanova`	API key string
Vercel	`vercel`	API key string
Novita	`novita`	API key string (`nvta_...`)
Akash	`akash`	API key string (`sk-...`)
Z.AI (GLM)	`zai`	API key string
GMICloud	`gmicloud`	API key string
Cerebras	`cerebras`	API key string (`csk-...`)
MegaNova	`meganova`	API key string

Notes:

AWS JSON can also include sessionToken.
Azure-style providers require provider-specific endpoints and identifiers (for example, a deployment name).
If you want to force Google AI Studio routing for Gemini models, set x-byok-provider: google (or byok.provider: "google").
Additional provider options may appear over time in the BYOK UI and provider-discovery endpoints.

Web-search-only providers

These providers are BYOK for web search enhancements, not chat model execution:

Provider	Slug
Tavily	`tavily`
Exa	`exa`
Kagi	`kagi`
Perplexity	`perplexity`
Valyu	`valyu`

Page reading providers

These providers read web pages for URL scraping, not chat model execution:

Provider	Slug	Reads
Firecrawl	`firecrawl`	Web pages, PDFs and documents, and stealth mode
Berrycrawl	`berrycrawl`	Web pages
Linkup	`linkup`	Web pages, when Linkup is the selected page reader

Page Reading Keys

Save a Firecrawl, Berrycrawl or Linkup key at https://nano-gpt.com/byok, and NanoGPT reads pages with it. You don’t need x-use-byok or byok.enabled. Which key a page read uses:

Standard reads use your Berrycrawl or Firecrawl key. If you saved both, NanoGPT tries one and falls back to the other, both on your keys.
PDFs and documents are parsed with your Firecrawl key. In web app chat and on /api/scrape-urls, a document URL fails if you saved only a Berrycrawl key, with a message asking you to add a Firecrawl key.
Stealth mode (stealthMode: true) uses your Firecrawl key. Without one, stealth reads use NanoGPT’s Firecrawl key and are billed as usual.
Linkup keys are used only when Linkup is the selected page reader: provider: "linkup" on /api/scrape-urls, or scraping: { "enabled": true, "provider": "linkup" } in chat.

If you have no key for a read, NanoGPT reads the page with its own key and bills it as usual.

No fallback to NanoGPT keys

Your key replaces NanoGPT’s. If a page can’t be read with your key, for example because your provider account is out of credits, that URL fails; NanoGPT does not retry it with a paid key. If a saved key can no longer be read, the request fails with HTTP 409 and code byok_credential_unreadable. Save the key again on the BYOK page or remove it.

Balance and spending limits

Balance checks and API key spending limits don’t count page reads your own key will serve. Request limits still apply, and model usage in chat is billed as usual.

When your keys are not used

Zero Data Retention: requests that require ZDR always read pages with NanoGPT’s Linkup key under NanoGPT’s ZDR agreement, never with your keys.
x402 payments: requests paid with x402 never use saved keys.
Per chat request: send scraping: { "enabled": true, "byok": false } to read pages with NanoGPT’s keys for that request. On /api/scrape-urls, remove the key to stop using it.

Teams

Team-billed requests use the team’s saved page reading keys when the team has BYOK enabled (prefer_team or require_team). A member’s personal key never serves a team-billed request. Without a matching team key, team-billed page reads use NanoGPT’s keys and are billed to the team as usual, in every team BYOK mode.

Saving a Berrycrawl key runs one test page read with it, which uses one Berrycrawl credit. Firecrawl and Linkup keys are checked without using credits.

Teams (BYOK)

Teams can also store provider keys and configure whether team-billed traffic should use team keys. Team settings endpoints (session-authenticated, not OpenAI-compatible):

GET   /api/teams/{teamUuid}/byok-settings
PATCH /api/teams/{teamUuid}/byok-settings
GET   /api/teams/{teamUuid}/provider-keys
POST  /api/teams/{teamUuid}/provider-keys
PATCH /api/teams/{teamUuid}/provider-keys
DELETE /api/teams/{teamUuid}/provider-keys?provider=<provider-slug>

Team key additions, replacements and ZDR changes require the acting member’s account confirmation under the same rule. Key changes notify the team owner’s stored email addresses. Existing team permissions still apply. BYOK modes:

disabled: BYOK off for the team.
prefer_team: use a team key when available; otherwise fall back to normal routing.
require_team: fail requests when no team key exists for the required provider.

Important behavior:

In prefer_team mode, team-billed traffic will not use a member’s personal BYOK keys unless the client explicitly opts in to BYOK on the request.

Security Notes

Never put provider keys in client-side code or public repos.
Store keys once in the web app and then enable BYOK per request.

Get Started

Endpoint Examples

API Reference

Miscellaneous

Integrations

Overview

Availability

Pricing

Configure Keys

Web UI

API (NanoGPT key required)

Use BYOK On A Request

Enable BYOK

Select a provider (optional)

Fallbacks (optional)

Provider Slugs

Chat / completion providers

Web-search-only providers

Page reading providers

Page Reading Keys

No fallback to NanoGPT keys

Balance and spending limits

When your keys are not used

Teams

Teams (BYOK)

Security Notes

​Overview

​Availability

​Pricing

​Configure Keys

​Web UI

​API (NanoGPT key required)

​Use BYOK On A Request

​Enable BYOK

​Select a provider (optional)

​Fallbacks (optional)

​Provider Slugs

​Chat / completion providers

​Web-search-only providers

​Page reading providers

​Page Reading Keys

​No fallback to NanoGPT keys

​Balance and spending limits

​When your keys are not used

​Teams

​Teams (BYOK)

​Security Notes

Overview

Availability

Pricing

Configure Keys

Web UI

API (NanoGPT key required)

Use BYOK On A Request

Enable BYOK

Select a provider (optional)

Fallbacks (optional)

Provider Slugs

Chat / completion providers

Web-search-only providers

Page reading providers

Page Reading Keys

No fallback to NanoGPT keys

Balance and spending limits

When your keys are not used

Teams

Teams (BYOK)

Security Notes