--- title: "Bring your own key (BYOK) — run Walnut AI on your own LLM providers" slug: "/help/account/ai-control-center/byok" topic: "account" last_updated: "2026-10-01T12:05:38.925Z" --- # 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. :::note[Good to know] Every API key is verified with the provider the moment you paste it. A rejected key is never stored — the error the provider returned is shown inline on the modal. ::: --- # 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.