# Bring your own API keys

> Run your agents on your own OpenAI or Anthropic account. Bringing your own keys takes your workspace off Bookbag credit metering for provider-backed models and bills LLM usage directly to your provider account.

By default, Bookbag runs your agents on its own model infrastructure and meters each reply in [credits](/docs/agents/credits). **Bring your own keys (BYO)** flips this: you add your own OpenAI and/or Anthropic API key, and provider-backed replies run on your account — billed by your provider, not metered against your Bookbag credit balance.

> **WHEN BYO MAKES SENSE:** BYO is for teams who already have provider accounts (with negotiated rates or committed spend), want all model usage on a single provider bill, or need a specific model not in the built-in catalog. If you'd rather not manage keys, the default credit system is simpler — see [Credits & usage](/docs/agents/credits).

## How BYO changes billing

Turning on BYO sets a workspace-level toggle. While it's on, replies that use a provider-backed model (OpenAI or Anthropic) bypass credit metering entirely — Bookbag uses your key and your provider bills you directly. Your Bookbag credit balance is untouched for those replies.

|  | Default (credits) | BYO enabled |
| --- | --- | --- |
| Who runs the model | Bookbag's infrastructure | Your OpenAI / Anthropic account |
| Who you pay | Bookbag (via your plan's credits) | Your model provider, directly |
| Credit balance | Decrements per reply by the model's credit cost | Not charged for provider-backed replies |
| Setup required | None — works out of the box | Add your provider key and enable the toggle |

> **YOUR KEY, YOUR SPEND:** With BYO on, usage runs against your provider account at your provider's rates and limits. Watch your provider's spend caps and rate limits the same way you would for any direct API integration.

## Enabling BYO

BYO is configured per workspace and requires an **admin** role. From your workspace LLM settings:

1. **Add a provider key** — Paste your OpenAI and/or Anthropic API key. Bookbag stores it for your workspace and shows it masked from then on. Adding a new key for a provider supersedes any prior one.
2. **Turn on the BYO toggle** — Enable "bring your own LLM" for the workspace. From now on, provider-backed replies use your key and skip credit metering.
3. **Verify in the playground** — Send a test message in the [playground](/docs/agents/playground) and confirm your agent replies. Usage now appears on your provider dashboard rather than your credit ledger.

> **TIP:** You can switch BYO off again at any time. With it off, provider-backed replies go back to running on Bookbag's infrastructure and metering credits.

## Key scope and security

- **Workspace-scoped.** Keys you add belong to your workspace and are used only for that workspace's agents.
- **Masked after entry.** Once saved, a key is shown only as a masked value — you can replace or delete it but not read it back.
- **Admin-only.** Adding, replacing, or removing keys and toggling BYO requires an admin role. See [Members & roles](/docs/workspace/members).
- **Per provider.** Add one active key per provider (OpenAI, Anthropic). Adding a new key for a provider deactivates the previous one.

> **CUSTOMER KEYS VS. PLATFORM KEYS:** The keys described here are *your workspace's* BYO keys. They are separate from any platform-level provider keys managed by Bookbag administrators, which power the default credit-metered infrastructure.

## What still uses credits under BYO

BYO only affects provider-backed model replies. Note that:

- Replies on the **Bookbag Local** model never use external keys and aren't metered either way.
- Adding and retraining **data sources** is always free — it never spent credits in the first place.
- If BYO is on but you have **no key for the provider** a given agent's model needs, that agent won't be able to run on that provider. Make sure each model you use has a corresponding key.

## Common questions

**Do I still need a Bookbag plan if I bring my own keys?**

Yes — your plan still governs seats, agent limits, channels, and other entitlements. BYO only changes how model replies are billed; it doesn't replace your subscription. See [Plans & billing](/docs/workspace/billing).

**Can I mix BYO and credits?**

The toggle is per workspace, so all provider-backed replies in that workspace follow the same setting. To run some agents on credits and others on your own keys, separate them into different workspaces.

**Where do I see my BYO usage?**

On your provider's dashboard (OpenAI / Anthropic). Bookbag's [Credits & usage](/docs/agents/credits) ledger tracks credit-metered activity; BYO replies don't appear there because they aren't metered.

**Is the open-source build metered at all?**

No. The self-hosted open-source build of Bookbag is unmetered — credits aren't enforced and usage is unlimited. Metering applies to the hosted cloud service.

## What's next

- [Credits & usage](/docs/agents/credits) — How the default credit system works and how to monitor it.
- [Models & model choice](/docs/agents/models) — Which models are available and what each costs.
- [Members & roles](/docs/workspace/members) — Who can manage keys and the BYO toggle.
- [Plans & billing](/docs/workspace/billing) — What your subscription includes alongside model usage.