Skip to main content

Bring your own key (BYOK) — run Walnut AI on your own LLM providers

Updated Oct 1, 2026

Overview

Bring Your Own Key (BYOK) lets admins route Walnut's AI features through their own LLM provider accounts instead of Walnut's shared keys. Every AI call — annotation writing, presenter notes, image generation, Insights AI, Buyer Xpert, demo agent tools — is billed to your provider account rather than deducted from your Walnut AI credits.

BYOK lives in the AI Control Center → Provider keys tab and is available to admins who can edit company settings.

Use BYOK when you want to:

  • Consolidate AI spend with an existing OpenAI, Anthropic, Google, or xAI contract.
  • Meet an internal policy that requires model traffic to run through your own tenant.
  • Choose a specific model per task tier (e.g., a faster model for autocomplete, a stronger one for long-form writing).

Before You Start

  • You must be an admin. BYOK controls are only visible to members with permission to edit company settings.
  • Your workspace must be entitled to BYOK. If you don't see the Provider keys tab, contact your Walnut account representative to enable it.
  • Have a provider API key ready. BYOK supports keys from OpenAI, Anthropic, Google, and xAI.

Set up BYOK

The Provider keys page is a single settings surface — no wizard, no Save button. Every control writes as soon as it changes.

1. Connect a provider​

  1. Open the AI Control Center from the left sidebar and select the Provider keys tab.
  2. Click Add provider and choose OpenAI, Anthropic, Google, or xAI.
  3. Paste the API key and click Save. Walnut checks the key with the provider before storing it. If the provider rejects the key, the failure reason appears in the modal — fix the key and try again.
  4. A verified key appears in the connected-providers list with a green Verified badge, the last four characters of the key, and the time it was last verified.

To rotate a key, click Replace on the row. To disconnect a provider, click Remove — removing the last connected provider deactivates BYOK entirely.

2. Map tiers to models​

Walnut groups AI work into tiers (for example, fast autocomplete vs. long-form writing vs. reasoning). Each tier lists the models your connected providers make available for that kind of work.

  • Pick a model from the dropdown for each tier. Walnut's recommended model is marked (recommended).
  • Choose Walnut default to leave a tier on Walnut's shared model. Any tier you leave on Walnut default keeps drawing Walnut credits.
  • Tiers are unavailable until at least one provider is connected.

3. Choose a failure policy​

The Failure policy switch controls what happens when your provider rejects a call:

  • Fall back to Walnut — the call reruns on Walnut's shared model and is billed to your Walnut credits. AI features stay available.
  • Stop — the AI feature returns an error to the user. Nothing runs on Walnut's model.

Until you pick one, the page shows a Not chosen chip and BYOK cannot be activated.

4. Choose content retention​

The Retain content toggle controls what Walnut stores for BYOK requests:

  • Content — Walnut stores the prompt and the model's response, the same as non-BYOK requests. Required for features that reuse context across turns.
  • Metadata only — Walnut stores request/response metadata (timestamps, token counts, tier) but discards the prompt and response body.

Both caveats on this row are worth reading: metadata-only mode disables features that depend on stored context, and neither mode changes what your provider stores.

5. Activate​

The Activate button lives in the page header. Walnut lists every unmet condition (the What's blocking activation panel) — for example, an unmapped required tier or a missing failure policy. Clear every blocker to enable the button.

If any tier is left on Walnut default, an acknowledgement appears warning you that those tiers will keep drawing Walnut credits. Tick the checkbox to confirm, then click Activate.

Once active, the header shows a green Active badge and the notice band inverts to confirm that traffic is now routed through your provider.

Outage handling

If a stored key starts failing while BYOK is active, the affected provider row turns red with the provider's own error text ("invalid_api_key — The API key provided is invalid.") and — under the Stop failure policy — a red Provider outage banner appears at the top of the page. From the banner you can:

  • Paste a new key to reopen the connect modal for that provider.
  • Fall back to Walnut to switch the failure policy to fallback mode without deactivating BYOK.

Under the Fall back to Walnut policy, the failing row is still surfaced but no outage banner appears — AI features keep working on Walnut's model until you rotate the key.

Change history

Every write is recorded in the Change history panel at the bottom of the page: who connected or removed a key, who remapped a tier, and who changed the policy or retention. Filter by action, provider, or free-text search; the trail is server-side and grows without limit.

Deactivate BYOK

Click Deactivate in the header to route AI traffic back to Walnut's shared model. Your stored keys, tier mappings, and policy choices are kept — reactivating BYOK does not ask you to reconfigure. Removing the last connected provider also deactivates BYOK, and the confirmation dialog spells that out before you confirm.

FAQ

Which AI features run on my keys?
When BYOK is active, every Walnut AI feature — editor AI mode, presenter notes, image generation, Insights AI, Buyer Xpert, demo-editing agent tools — routes to whichever model you mapped to the corresponding tier.

What happens to my remaining Walnut AI credits?
Credits are not consumed while BYOK is active for a tier you have mapped. Tiers left on Walnut default (or reached via the fallback policy) still deduct credits normally.

Can I use BYOK for only some AI features?
Yes — per-tier mapping is the mechanism. Leave a tier on Walnut default to keep that class of AI work on Walnut's model.

Is my API key visible after I save it?
No. Walnut only ever shows a masked hint (last four characters) and the time the key was last verified. Keys are write-only from the UI.

Was this helpful?