Skip to main content

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

Updated Oct 6, 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 section decides what Walnut does when your own provider refuses a call. It is a single switch labeled Fall back to Walnut, and the two positions are the two downtime options for your account:

  • On — Fall back to Walnut. Walnut retries the call on its own shared model so the action succeeds, and the retry draws Walnut AI credits at the usual rate. AI features keep working through a provider outage, on credits, until the stored key is fixed.
  • Off — Stop the feature. The action fails and the user is told to contact an admin. Nothing runs on Walnut's model and no credits are spent. AI features stay down for the account until the stored key is fixed.

Until an admin picks a position, the row shows a Not chosen chip and BYOK cannot be activated — the server treats an unset policy the same as Stop the feature, and activation is blocked so this choice is never made silently.

The failure policy also controls what the account sees during a live outage: see Outage handling below for the banner that appears under Stop the feature and the one-click way to switch to Fall back to Walnut without leaving the page.

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​

Nothing routes to your provider until an admin activates BYOK. Connecting a key, mapping tiers and choosing a policy only stages the configuration — AI features keep drawing Walnut credits in the meantime, and the page's notice band says so (Still running on Walnut credits).

Activation is a deliberate review step: the admin reads what the account is about to send to its own provider, clears any blockers Walnut lists, acknowledges any warnings, and then presses the activate button in the page header.

  1. Open the Activation section. Walnut lists every unmet condition in the What's blocking activation panel — for example, a mapped model that is no longer on Walnut's allowlist, or a missing failure policy. Clear every blocker to enable the button.
  2. If any tier is left on Walnut default, an acknowledgement appears naming those tiers and warning that they will keep drawing Walnut credits. Tick I understand these will keep drawing Walnut credits to confirm.
  3. Press Route AI traffic to my provider in the page header (a sticky bar with the same action also appears at the foot of the page once the setup is ready). Activation takes effect on the next AI action.

Once active, the header status chip reads Active — on your keys, the notice band inverts to Running on your provider, and the Activation section becomes a summary of the failure policy, retention and whose bill AI spend lands on.

Monitor BYOK usage

Once BYOK is active, tokens are billed by your provider at the rates you have negotiated with them instead of drawing Walnut credits. The AI center → Usage tab is where you see what that traffic looks like, side by side with whatever is still running on Walnut credits.

Pick a time range from the pill switcher in the header: 7d, 30d or 90d. Admin accounts with more than one key connected also get a view switcher — All, Walnut, and one tab per connected provider — so you can read the whole account, the Walnut‑credit side on its own, or any single key.

Your provider key​

A card at the top of the page names what is connected and how healthy it is:

  • The provider name, the models you have mapped to it, and a four‑character hint of the key (sk-••••abcd). That hint is the only representation of the key that ever leaves the server.
  • A status dot — green Healthy, red Failing, or grey Not connected.
  • Features routed here — of the features BYOK can serve on this workspace, how many run entirely on your own key.
  • Calls this term and Images generated this term. If no provider you have connected offers an image model, the images line reads Runs on Walnut instead of a count.
  • Credit cost — None while BYOK is active.

A Manage provider keys → link on the card jumps to the Provider keys tab.

Usage by feature​

A single card shows the three ways a call gets paid for, side by side and never added together:

  • Walnut credits — a donut of the credits drawn from your balance, broken down by feature, with the credit balance card beside it.
  • Your [provider] key — input tokens, output tokens and calls on your own key. The Walnut credits used line underneath is always 0 — the whole point of this column is that the token usage above it drew no credits.
  • Included in your plan — a footnote under the donut counting the credits that ran on unlimited features without touching the balance.

An information note under the token totals reads: "A floor, not a total. Streamed calls do not report usage back to us. Your provider invoice is the authority." Treat the figures as a running view; your provider invoice remains the authoritative record of what you were billed.

Usage by model, feature and person​

Three sortable tables, side by side, over the same own‑key traffic in the selected range:

  • Model — tokens and calls per model. In the All view each model is prefixed with its provider; in a single‑provider view the prefix drops.
  • Feature — the same totals grouped by Walnut feature (AI Mode, Buyer Xpert, image generation, agent tools, and so on).
  • Person — the same totals grouped by the workspace member who ran the calls. Traffic from prospects viewing a demo is attributed to the demo owner.

Each table sorts by Name, Calls or Tokens — click a column header to sort, click again to reverse. Each table sorts independently. Rows missing a model, member or provider name are grouped under Unknown model, Unknown member or Unknown provider rather than dropped, so their tokens still show up in the total.

What runs where​

A second card answers "BYOK is on — why is the Walnut balance still moving?" by grouping every AI feature by what it would take to move it onto your key:

  • On your [provider] key — fully routed, no credits.
  • Mostly on your [provider] key — the feature runs on your key for every tier your providers can serve; only the tiers no connected provider offers a model for fall back to Walnut credits.
  • Eligible, still on Walnut credits — features that ask for a tier you have not mapped yet. The group header links to Map more tiers →.
  • Charged as Walnut credits — specialist vendors (for example, AI presenter avatars) that no provider key can replace. Walnut runs them on its own vendor accounts and re‑bills what they cost as credits.
  • Included in your plan — vendors your plan covers outright, such as speech‑to‑text and voice synthesis. No credit figure, no bill.

If no provider is connected, the eligible group becomes Every AI feature is on Walnut credits, with a Connect a provider key → link in the header. Your tier mappings are kept and take effect again the moment a key is connected.

Credit usage over time​

On a BYOK account the stacked‑bar trend chart below the cards is titled Walnut credit usage over time, with a note that calls on your own key are not included. In a single‑provider view, both the trend chart and the credit‑priced users table below it are hidden — neither has a figure that belongs to one key, and the per‑model/feature/person tables above are the breakdown for that view.

Failing‑key banner​

A failing credential surfaces as a banner that stays visible across every tab under /ai:

  • Under the Stop failure policy it is a red AI features are unavailable across this account banner — nothing is falling back and every AI feature is down until the key is fixed.
  • Under the Fall back to Walnut policy it is a softer Your [provider] key is failing notice — AI keeps working on Walnut's model and draws credits until you rotate the key.

Both banners carry a button that jumps straight to the Provider keys tab, where the failing row and its error message are also surfaced (see Outage handling below).

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.

Key health monitoring​

Walnut re-verifies every stored provider key once a day with the same one-token probe that runs when you connect a key, so a key that was revoked, had its permissions changed, or ran out of quota is surfaced on the Provider keys page before the next person tries to use it.

A key only switches to failing when the provider's response is clearly about the credential — an invalid or revoked key, insufficient permissions, an exhausted quota or billing balance, or (for Azure) an unreachable endpoint or missing deployment. A rate-limit, a 5xx, a timeout or any other transient blip leaves the row exactly as it was and is retried on the next sweep, so a provider having a bad hour never flips a healthy key to failing.

When a key transitions into failing — whether the daily sweep caught it or a live AI call did — every admin who receives AI alerts for the account is emailed once with the subject Your <provider> API key in Walnut needs attention. The email names the provider and the reason (for example, "This API key has no quota or credit left with the provider") and links straight to the AI Control Center. A key that stays broken is one email, not one a day: the next alert for the same provider only fires after the key has been fixed and later fails again.

The row's own status indicator — the red provider row, and the Provider outage banner under the Stop policy — is driven by the same mechanism, so clearing the failure on the Provider keys page (by pasting a new key or switching the failure policy) also clears the state the next email would alert on.

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

An admin can turn BYOK off at any time, and deactivation deletes the stored keys — there is no pause.

Click Deactivate BYOK in the page header. The confirmation dialog is titled Deactivate BYOK and delete your keys? and spells out the consequence: Walnut disconnects every connected provider, deletes the stored keys, and routes AI features back to Walnut credits on the next action. Confirm with Disconnect and delete keys, or back out with Keep BYOK on.

What survives a deactivation:

  • Your model choices per tier.
  • Your failure policy.
  • Your content retention setting.

What does not:

  • The API keys themselves — they are deleted from Walnut. To turn BYOK back on, paste a key for each provider again; the rest of your setup is still there and routing resumes once you activate.

Removing the last connected provider from the Provider keys list has the same effect: that key is deleted and BYOK turns off. The remove dialog uses the same consequential wording in that case. Removing one of several keys only deletes that one key, and any tier mapped to it falls back to Walnut's model under your failure policy.

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?