Bring Your Own AI Key (BYOK)
What BYOK Does
BYOK routes your workspace's 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.
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.
Configuring
- Open Settings and find the AI API Key (Bring Your Own) card. Only organization admins can change these settings.
- 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:
- "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 BYOK is unset — or a BYOK call fails — the router uses the platform key so the operator's session doesn't die mid-question. Two 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.
How Usage Attribution Changes
- With BYOK active: calls bill to your provider account per token. They do not draw from the workspace 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.