Secrets and encryption

Fontana keeps credentials out of workflow config and browser responses. Connector secrets, MCP tokens, LLM API keys (BYOK), and service credentials resolve from HashiCorp Vault inside your workspace at execution time. Encryption protects data on the wire and on disk through infrastructure and TLS controls described below.

Secrets model

Secret type	Storage	When resolved	Browser exposure
BYOK (LLM keys)	Vault KV fontana	Server actions at inference time	Never returned; Admin shows metadata only
Connector credentials	Vault placeholders in workflow config	Workflow engine at run time	Never embedded in exported config
MCP OAuth tokens	Vault	Server-side MCP calls	Never returned to Flow UI
Service auth (engine, observability-api)	Vault-backed OAuth clients	Backend token introspection	Not used by browser sessions

Vault is seeded in-cluster during workspace provisioning. Production deployments do not rely on plaintext seed files on the host or in ConfigMaps as the system of record.

Write-only from Admin

When you save a BYOK or connector secret in Admin, Fontana stores the value in Vault and confirms success without echoing the secret back. Rotation replaces the stored value; prior runs do not embed historical keys in workflow JSON.

BYOK scopes

LLM credentials support org, team, and person scopes so you can align keys with procurement and chargeback. Resolution is fail-closed: if no key exists at the required scope, the call does not silently fall back to another tenant’s or Fontana-owned credentials.

See Bring Your Own Key (BYOK) for Admin paths and gateway approval.

Secret rotation

Fontana stores secret values in Vault; rotation replaces the stored value without embedding secrets in workflow JSON or returning them to the browser.

Secret class	Who rotates	Typical procedure
BYOK (LLM keys)	Your admin in Admin → Models → API Keys	Save a new key at the same scope; old value is overwritten in Vault
Connector and MCP credentials	Your admin in Flow Admin or node settings	Update the Vault-backed secret; next run resolves the new value
SCIM bearer token	Your identity team in Zitadel Management Console	Rotate SCIM token in Zitadel and update the corporate IdP SCIM app configuration
Service OAuth clients (engine, observability-api)	Platform operator during upgrade or runbook	Rotated through Vault-backed provisioning as part of controlled deploys
Vault root / unseal material	Platform operator	Runbook-driven; not exposed to workspace users

After BYOK or connector rotation, historical workflow config does not retain prior secret values. Runs that already completed used the key effective at execution time; audit metadata may record that a key was updated without storing the secret itself.

Composite configuration backup does not include BYOK values. After disaster recovery, restore secrets from a Vault Raft snapshot in addition to application backup. See Backup and restore.

Encryption in transit

For the full hop-by-hop transmission table (public TLS vs in-cluster HTTP), see Network and hardening.

Hop	Protection
Internet to your workspace hostname	TLS at the host edge (ACME-managed certificates)
Edge to in-cluster ingress	HTTP on localhost or bridge (same host)
In-cluster service to service	HTTP on cluster network; NetworkPolicy restricts which pods may talk
Pods to external LLM or connector APIs	HTTPS to provider endpoints (egress allow on port 443)

Compensating controls for plain HTTP inside the cluster: NetworkPolicy default-deny, cluster-per-tenant separation, and no multi-tenant pod sharing on the data plane. Full table: Transmission boundary.

Encryption at rest

Production hosts use encrypted block storage for the dedicated data volume that backs all workspace PVCs: Postgres, Convex backend data, workflow-engine file store, and Vault Raft.

Fontana does not apply a separate application-layer field encryption on workflow datasets. Protection relies on infrastructure encryption plus workspace isolation so only your cluster’s workloads mount your volumes.

Workflow run data (uploads, Arrow datasets, audit and lineage sidecars, exports) persists on a dedicated ReadWriteOnce PVC per workspace, retained across Helm upgrades.

Backup and disaster recovery

• Composite configuration backup (Admin) exports Convex configuration; it does not include BYOK secret values.
• Vault Raft snapshot is the authoritative restore path for secrets and BYOK after disaster recovery.
• Volume-level procedures cover Postgres, Convex, and workflow-engine PVCs; see Backup and restore.

Related documentation

• Workspace isolation - separate Vault per workspace
• Identity and access - Zitadel and RBAC (distinct from BYOK)
• Secret rotation - BYOK, connectors, SCIM tokens
• Immutable audit trail - security events when secrets and admin settings change
• SOC 2 control summary - secrets and encryption rows