Update from code changes: BYO org AI provider API keys

[mintlify]

Summary

Document the new AI providers & models card that lets org admins BYO Anthropic/OpenAI keys for Ask AI and control which models are exposed to users.

Changes

• Added a "Bring your own AI providers and models" section to guides/ai-agents/getting-started.mdx covering:
  • Where to set keys (Ask AI → Settings → General → AI providers & models) and feature-flag gating.
  • Fallback behavior when a provider key is set or removed.
  • The org default-model dropdown surfacing providers the org has keyed.
  • Per-provider Available to users toggle and Allowed models allow-list, including the "at least one model" guarantee.
  • Anthropic-only BYOK auto-hides OpenAI (never falls back to instance OpenAI).
  • Key-gated models (Claude Opus 4.8 unlocks once the org's Anthropic key can access it).
  • The Active badge, all-providers success callout, and per-provider guidance when a visible provider has no org key.
  • Security model (encryption at rest, providerApiKeysSet boolean, redacted providerApiKeyHint, keys vs. visibility must be updated in separate requests).
  • v1 scope: chat/agent utility calls (including data-app clarification and sandbox generation); embeddings and eval judge still use the instance key.
• Added a note to guides/ai-agents/reviews.mdx that Reviews is automatically paused while any BYO AI provider key is set.

Context

Sourced from:

• feat(common): add provider API key types and feature flag for org AI keys lightdash#25192
• feat(backend): add OrgAiCopilotConfigResolver overlaying org API keys lightdash#25193
• feat(backend): org-aware AI model options and provider key settings lightdash#25194
• feat(backend): resolve org AI provider keys in AiAgentService model calls lightdash#25195
• feat(frontend): org AI provider API keys card in Ask AI general settings lightdash#25196
• fix(ai): don't require admin ability to resolve org default model in Slack lightdash#25265
• feat: org-level AI model visibility (provider toggles + allowlist + key-gated opus 4.8) lightdash#25288
• fix(ai): robust BYO-key model resolution — timeout, dated-id match, ambient fallback lightdash#25323
• feat(frontend): merge AI provider keys + model availability into one card lightdash#25336
• fix(ai): run data-apps sandbox on a BYO org's own Anthropic key lightdash#25345
• feat: confirm BYOK API keys are in use on the AI providers settings card lightdash#25352

Update history

• Initial: documented the BYO org AI provider API keys card, feature-flag gating, fallback behavior, security model, and v1 scope.
• Follow-up (feat: org-level AI model visibility (provider toggles + allowlist + key-gated opus 4.8) lightdash#25288, fix(ai): robust BYO-key model resolution — timeout, dated-id match, ambient fallback lightdash#25323, feat(frontend): merge AI provider keys + model availability into one card lightdash#25336): reflected the merged AI providers & models card, added per-provider availability toggle and allowed-models allow-list, Anthropic-only-BYOK auto-hides OpenAI, key-gated Claude Opus 4.8, "separate requests for keys vs. visibility" rule, and the reviews auto-pause on BYO keys. Removed the review-classifier line from the "still uses instance key" list since reviews are now paused entirely for BYO orgs.
• Follow-up (fix(ai): run data-apps sandbox on a BYO org's own Anthropic key lightdash#25345, feat: confirm BYOK API keys are in use on the AI providers settings card lightdash#25352): documented the new BYOK confirmation UI — Active badge, all-providers-on-org-key success callout, and per-provider guidance when a visible provider has no org key. Extended the "where the org key is used" list to call out that data-app clarification and sandbox generation now both run on the org's Anthropic key for BYO orgs.

[github-actions]

🤖 Documentation Bot

✅ All checks passed! No issues found.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
lightdash	🟢 Ready	View Preview	Jul 8, 2026, 12:44 AM

[github-actions]

🤖 Documentation Bot

✅ All checks passed! No issues found.

[mintlify]

Update from code changes updated this PR.

Expanded the BYO AI keys docs with provider and model visibility controls, and noted reviews pause when BYO keys are set.

Source PRs

• lightdash/lightdash#25192 — feat(common): add provider API key types and feature flag for org AI keys
• lightdash/lightdash#25193 — feat(backend): add OrgAiCopilotConfigResolver overlaying org API keys
• lightdash/lightdash#25194 — feat(backend): org-aware AI model options and provider key settings
• lightdash/lightdash#25195 — feat(backend): resolve org AI provider keys in AiAgentService model calls
• lightdash/lightdash#25196 — feat(frontend): org AI provider API keys card in Ask AI general settings
• lightdash/lightdash#25265 — fix(ai): don't require admin ability to resolve org default model in Slack
• lightdash/lightdash#25288 — feat: org-level AI model visibility (provider toggles + allowlist + key-gated opus 4.8)
• lightdash/lightdash#25323 — fix(ai): robust BYO-key model resolution — timeout, dated-id match, ambient fallback
• lightdash/lightdash#25336 — feat(frontend): merge AI provider keys + model availability into one card

[github-actions]

🤖 Documentation Bot

✅ All checks passed! No issues found.

[mintlify]

Update from code changes updated this PR.

Documented the BYOK confirmation UI on the AI providers card and noted data-app sandbox generation now uses BYO Anthropic keys.

Source PRs

• lightdash/lightdash#25192 — feat(common): add provider API key types and feature flag for org AI keys
• lightdash/lightdash#25193 — feat(backend): add OrgAiCopilotConfigResolver overlaying org API keys
• lightdash/lightdash#25194 — feat(backend): org-aware AI model options and provider key settings
• lightdash/lightdash#25195 — feat(backend): resolve org AI provider keys in AiAgentService model calls
• lightdash/lightdash#25196 — feat(frontend): org AI provider API keys card in Ask AI general settings
• lightdash/lightdash#25265 — fix(ai): don't require admin ability to resolve org default model in Slack
• lightdash/lightdash#25288 — feat: org-level AI model visibility (provider toggles + allowlist + key-gated opus 4.8)
• lightdash/lightdash#25323 — fix(ai): robust BYO-key model resolution — timeout, dated-id match, ambient fallback
• lightdash/lightdash#25336 — feat(frontend): merge AI provider keys + model availability into one card
• lightdash/lightdash#25352 — feat: confirm BYOK API keys are in use on the AI providers settings card
• lightdash/lightdash#25345 — fix(ai): run data-apps sandbox on a BYO org's own Anthropic key