Bring Your Own AI Key (BYOK)
What BYOK Does
BYOK routes AI calls through your own provider account instead of ET Ducky's platform keys. AI cost moves from per query (the platform's plan tiers) to per token (your provider invoice). Everything else — prompt engineering, the Smart Reports planner, alert enrichment, live sessions — works unchanged.
A key can be set at two levels: once for the whole workspace, and again on any individual organization that needs a different one. See Where a key lives below — on a multi-client workspace that choice is the difference between configuring one key and configuring thirty.
Supported providers
| Provider | Key format | Model field | Endpoint field |
|---|---|---|---|
Anthropic (anthropic) | sk-ant-... | Optional override (e.g. claude-haiku-4-5-20251001) | Not used |
OpenAI (openai) | sk-... | Optional override (e.g. gpt-4o-mini) | Not used |
Azure OpenAI (azure-openai) | Azure OpenAI key | Required — your deployment name | Required — https://{resource}.openai.azure.com |
Leaving the model blank uses the provider's default model.
Where a Key Lives: Workspace Default vs Per-Org Override
There are two places a key can be stored, and exactly one rule for which one gets used.
- Workspace default — one key for the whole workspace. Every organization that has no key of its own uses it. This is the normal setup for an MSP: one provider account, one invoice, every client's AI calls running through it. There is only ever one workspace default.
- Per-organization override — a key set on a single organization. You can set as many of these as you like, one per org.
The organization's own key always wins. That holds even when it names the same provider as the workspace default — "Anthropic here, a different Anthropic account there" is exactly the case overrides exist for, typically a client who wants their AI spend on their own vendor invoice rather than yours.
Resolution order for any given AI call:
- The organization's own key, if it has one.
- Otherwise the workspace default, if one is set.
- Otherwise the platform pool, which draws from your plan's monthly query quota.
Before this existed, a key had to be pasted into every client organization separately — and again into each new one. If you set keys that way, they are per-org overrides and still take precedence; you can clear them one at a time as you move clients onto a workspace default.
Configuring
- Open Configuration and find the AI API Key (Bring Your Own) card. Only organization admins can change these settings.
- Use the scope bar at the top of the card to choose where the key lands. The first entry is Workspace default (all organizations); your organizations are listed below it, and each one says whether it already has a key of its own. Selecting an organization switches the dashboard to that organization; selecting the workspace default re-points the same form at the workspace without a reload.
- Pick a provider from the dropdown. The key, model, and (for Azure) endpoint rows appear as needed.
- Paste the key and click Save. The key is encrypted at rest and is never returned to the browser afterward — the card shows a "key saved" badge instead, and the key field reads "A key is saved — leave blank to keep it."
- To change just the model or endpoint later, leave the key field blank and save; the existing key is kept.
- To revert to the platform pool, click Clear (or save with the provider set back to none).
Azure OpenAI saves are rejected without both an endpoint URL and a deployment name in the Model field.
Validation Status
The status line under the card tracks how the key is behaving in real use. Each scope keeps its own status — the workspace default has one, and every organization with an override has its own. Switch the scope bar to see the one you care about; a failing workspace default otherwise shows up as several organizations each looking healthy while none of their calls land on your key.
- "Key saved — not yet used" — saved, but no AI call has run against it yet.
- "Key active — last validated <time>" — the most recent BYOK call succeeded; the timestamp updates as calls succeed.
- "Last failed: <time> (<reason>). Falling back to platform key." — the most recent failure, with a reason code:
| Reason code | Meaning | Fix |
|---|---|---|
auth_invalid | The provider rejected the key (revoked, mistyped, wrong resource). | Generate a fresh key and re-save. |
rate_limited | Your provider account hit its rate limits. | Raise the provider-side limit or spread out heavy workloads. |
quota_exceeded | Your provider account's spend cap or quota is exhausted. | Increase the provider quota or wait for the cycle to reset. |
network | The provider endpoint was unreachable (outage, bad Azure endpoint URL). | Verify the endpoint URL; check the provider's status page. |
Fallback to the Platform Pool
When no key applies at either level — or the key that applies fails — the router uses the platform key so the operator's session doesn't die mid-question. Three consequences worth internalizing:
- Fallback calls consume platform queries. A silently failing key can drain your tier's monthly pool. If the status line shows recent failures, fix the key promptly.
- Fallback is per call, not a mode switch. The router retries your key on the next call, so a transient provider blip self-heals without intervention.
- Fallback goes to the platform, not to the other level. An organization with its own failing key falls back to the platform pool — it does not quietly start spending on the workspace default. Each level's key is used or it isn't; there is no second-choice hop between them.
- Fallback is quota-checked, so it can be refused. If the organization's monthly platform quota is already exhausted, the fallback call is declined rather than run, and the query fails with a quota error. A broken key plus a spent quota is the combination that actually stops work — another reason to act on the failure reasons above rather than leaving them.
How Usage Attribution Changes
- With BYOK active: calls bill to your provider account per token. They do not draw from the organization’s query pool. The AI Usage card still records tokens, requests, and usage types, so observability is identical.
- Without BYOK (or on fallback): each query draws one unit from the organization's pooled monthly quota (see Pricing & Billing).
Security: the key is encrypted at rest, never written to logs, and never included in API responses — the settings endpoint returns only the provider, model, endpoint, a has-key flag, and the validation timestamps.