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.
View as MarkdownBy default, Bookbag runs your agents on its own model infrastructure and meters each reply in 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.
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.
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 |
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:
- 1Add a provider keyPaste 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.
- 2Turn on the BYO toggleEnable "bring your own LLM" for the workspace. From now on, provider-backed replies use your key and skip credit metering.
- 3Verify in the playgroundSend a test message in the playground and confirm your agent replies. Usage now appears on your provider dashboard rather than your credit ledger.
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.
- Per provider. Add one active key per provider (OpenAI, Anthropic). Adding a new key for a provider deactivates the previous one.
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.