Bring Your Own Key (BYOK)

DeepRead's BYOK feature lets you connect your own AI provider API keys to process all documents through your account. When active, every LLM call routes through your keys instead of DeepRead's, so model spend lands on your provider account. BYOK is an Enterprise feature. Enterprise accounts have no monthly page quota; pages are billed at the account's per-page rate.

Enterprise plans. Every account can open the BYOK page and read the tier map, but adding, switching or removing a key on another plan is refused with 402 naming the plan that has it.

Three ways to set it up

DeepRead's deep-extract engine runs two different model families in parallel (a primary OCR reader + a secondary cross-checker) and uses an LLM judge to reconcile them. BYOK preserves that two-model design across three setups:

Pick the path that matches the accounts you already have. The dashboard BYOK page walks you through it with a path picker — choose the path, then add the right key(s).

Slots: primary and secondary

Each user has two slots. You can store one active key per slot:

• Primary drives ocr_primary plus auxiliary models (rotation, judge, extraction, quality review).
• Secondary drives ocr_secondary — the cross-check.

You don't have to fill both slots. With only a primary, single-direct or single-OpenRouter mode kicks in automatically. With both filled on different providers, you get the cross-family pair.

How it works under the hood

Dashboard -> Add Key(s) to Slot(s) -> Validated & Encrypted -> Stored in DB
                                                                 |
API Request -> Job Created -> Resolve Slot-Aware Keys -> Pipeline Uses Your Keys

1. You store keys via the dashboard BYOK page; each key is validated against the provider's API before saving.
2. Keys are encrypted at rest using Fernet (AES-128-CBC + HMAC-SHA256).
3. Every subsequent job automatically detects the right slot for each pipeline step.
4. No changes to your API calls — same endpoints, same X-API-Key header.

Supported providers

Model tier swapping

When you use a direct provider key (OpenAI or Google), each of DeepRead's default models is swapped for a model from your provider in the same quality tier.

The dashboard "What runs on your keys" table shows you the exact mapping for your current setup.

What changes for your billing

Managing your keys

From the dashboard BYOK page you can:

• Pick a path (OpenRouter / cross-family / single direct) — the dialog adapts to your choice
• Add a key per slot — validated against the provider before saving
• Toggle a slot on/off without deleting — flip back to DeepRead processing whenever
• Replace a key in a slot
• Remove a key — clears the ciphertext from the database
• View your BYOK Jobs — a dedicated tab on the BYOK page shows jobs that ran on your keys, with per-job provider and cost. Your regular /dashboard/jobs page only lists DeepRead-billed jobs.

The mode banner at the top of the BYOK page tells you exactly which path is active (or off), and the "Savings this cycle" card shows how many pages and dollars you've shifted off DeepRead's quota.

Security

• Keys are encrypted at rest with Fernet symmetric encryption
• The encryption key is stored separately from the database
• Keys are validated against the provider's API before storing
• Deleting a slot's key clears the ciphertext immediately
• Key hints (last 4 characters) are shown for identification only — full keys are never returned by the API