Bring Your Own Key (BYOK)
Bring Your Own Key (BYOK) is how you connect Fontana to LLM gateways and model providers using credentials your organisation already holds. Fontana does not operate a shared vendor LLM account for your workspace.
Your keys are stored securely in a HashiCorp Vault. You can approve which gateways and models are reachable in production, ensuring that chat, agent, workflow AI, and embedding calls are routed through your contracts—so spend, logging, retention, and training policy always remain under your control.
Why BYOK matters
Section titled “Why BYOK matters”BYOK keeps AI spend and data policy aligned with procurement you already run:
- No shared Fontana model pool - inference uses keys and gateways you provision
- Contractual control - retention, training, and regional routing follow your provider agreements; see Zero Data Retention (ZDR) where supported
- Cost attribution - scope keys at org, team, or person level for clearer chargeback
- Fail-closed secret handling - keys are never returned to the browser or embedded in workflow config
After keys are set, choose which gateways and models are allowed in Gateways and Models. BYOK supplies credentials; those pages govern routing and the production model catalogue.
Key storage and scopes
Section titled “Key storage and scopes”BYOK secret values live in Vault KV mount fontana only. They are write-only from Admin → Models → API Keys: the UI shows whether a key is set, when it was updated, and who set it, but never returns the raw value to the browser.
You can scope each provider key at three levels:
| Scope | Use when |
|---|---|
| Org (global) | One deployment-wide key shared by all teams |
| Team | A team-specific key for cost attribution or provider segregation |
| Person | An individual user’s key for personal or experimental use |
At runtime, Fontana resolves keys in order person → team (when a team context applies) → org. The first match wins, so narrower scopes override broader ones without shadow usage. For chat and agent turns, team context comes from a workflow the authenticated user can read; an unreadable or spoofed workflow id does not open another team’s key path. Updates in Admin are visible on the next model call without restarting workspace pods.
Configure in Admin
Section titled “Configure in Admin”Open Admin → Models → API Keys to set, verify, and clear keys per provider. Use the scope selector to choose org, team, or person before editing a provider card.
| Step | What you do |
|---|---|
| Set a key | Paste or rotate the provider credential; Fontana writes it to Vault only |
| Verify | Run the built-in check against the provider’s authenticated endpoint; the card shows Verified, Invalid key, or Unverified |
| Approve models | Move to Models → LLMs to choose which model ids are reachable in production |
| Embedding profile | On Models → Embeddings, select the single active embedding profile: in-cluster TEI or Infinity, an OpenAI-compatible gateway (OpenAI, OpenRouter, LLM API), or Amazon Bedrock Titan using your AWS credentials |
Permissions: viewing Models requires platform:read or ai:page. Setting or clearing keys requires platform:write; team-scoped keys also require teams:admin for the selected team.
Supported providers include OpenAI, OpenRouter, LLM API, Anthropic, Groq, Google Generative AI, Mistral, NVIDIA, AWS Bedrock (three-field credentials), Custom & Self-Hosted endpoints (base URL plus optional API key for Ollama, LM Studio, vLLM, and similar), and additional gateways on Gateways.
What BYOK powers
Section titled “What BYOK powers”BYOK credentials feed every governed LLM path in Fontana:
| Surface | How BYOK is used |
|---|---|
| Agents and Flow chat | Model calls for conversation, tool use, and automation |
| Workflow AI | Natural-language operation compile and AI-assisted canvas steps |
| Knowledge Graph | Embedding calls when the active embedding profile targets an external gateway (the default in-cluster TEI profile needs no key) |
Gateway choice, model catalogue approval, and ZDR posture are configured separately on Gateways, Models, and Zero Data Retention (ZDR).
Distinct from connector secrets
Section titled “Distinct from connector secrets”BYOK keys are for LLM gateways only. Connector credentials, MCP OAuth tokens, and REST API secrets use a different Vault resolution path and admin surfaces ({{secret.NAME}} placeholders in workflow node config). See Data for connector secret handling and Tools and MCP for MCP credential storage.
Audit and backup
Section titled “Audit and backup”BYOK configuration changes are in scope for the immutable security audit trail. This allows tracking any key changes within your org.