Skip to content
Back to

Secrets and encryption

Fontana keeps credentials out of workflow config and browser responses. Workspace secrets, MCP header values and 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

Section titled “Secrets model”
Secret type Storage When resolved Browser exposure
Identity SMTP (Zitadel password-reset mail) Vault KV fontana (system/ZITADEL_SMTP_*) Admin save, then Zitadel send time Never returned; Admin shows metadata only
Workspace secrets (REST API and Data Connector credentials) Vault, per workspace; nodes hold {{secret.NAME}} references Workflow engine at run time, from the workflow’s own workspace Never returned; the workspace Config tab shows names and who last set them
MCP header values Vault Server-side MCP calls Never returned; AI → Tools shows Set or Not set
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 initialised during workspace provisioning by an idempotent Job that stores its unseal material as a Kubernetes Secret in the workspace namespace. Vault itself remains the system of record for secret values.

BYOK scopes

Section titled “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

Section titled “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
Identity SMTP (Zitadel password-reset mail) Your admin in Admin → Email Save host, from, user, and password; Convex writes Vault and updates Zitadel immediately
Workspace secrets (REST API and Data Connector credentials) Workspace editors and admins on the workspace Config tab Replace the value; the next run executes every node that uses the secret with the new value
MCP credentials Your admin on AI → Tools Replace the header value or reconnect OAuth; the next MCP call uses 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 (workflow engine, observability API) Platform operator during upgrade or runbook Rotated through Vault-backed provisioning as part of controlled deploys
Graph database credentials Platform operator Rotate in Vault; redeploy so dependent services pick up the new value
Vault root / unseal material Platform operator Runbook-driven and escrowed outside the install; never part of a backup or an export; every restore checks it is in place first

After BYOK or workspace secret rotation, historical workflow config does not retain prior secret values. Runs that already completed used the key effective at execution time; the Activity log records that a workspace secret was set, replaced, or deleted, by name, without storing the value.

Fontana Files never hold secret values: BYOK keys, workspace secrets, and chat tokens live only in the secret store. MCP and external agent connections are files in the system namespace in Fontana Files, and their header values, bearer tokens, and OAuth credentials live only in the secret store. After disaster recovery, restore secrets from the secret-store export in the nightly backup, which both backup modes and every fontana export carry. See Backup and restore.

Encryption in transit

Section titled “Encryption in transit”

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

Hop Protection
Internet to your workspace hostname TLS at the host edge (ACME-managed certificates)
Edge to workspace ingress HTTP on localhost or bridge (same host)
Workspace-internal 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 between pods: NetworkPolicy default-deny, namespace separation per workspace, and no multi-tenant pod sharing on the data plane. Full table: Transmission boundary.

Encryption at rest

Section titled “Encryption at rest”

Production hosts use encrypted block storage for the dedicated data volume that backs workspace persistent volumes: databases, backend data, Knowledge Graph graph store, workflow file store, and Vault file storage.

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, JSONL datasets, audit and lineage sidecars, exports) persists on a dedicated ReadWriteOnce PVC per workspace, retained across Helm upgrades.

Backup and disaster recovery

Section titled “Backup and disaster recovery”
  • Tenant configuration such as models and MCP connections is kept as files in Fontana Files, and those files hold no secret values (BYOK, workspace secrets, chat tokens). A fontana export keeps secrets apart from the namespace files, in its secret-store file.
  • The secret-store export in the nightly backup is the authoritative restore path for secrets and BYOK after disaster recovery. It is part of both backup modes and of every fontana export.
  • The nightly backup covers your Fontana Files namespaces in both modes, and the databases and graph store in full mode; see Backup and restore.
  • Unseal material stays with each install and is escrowed separately. fontana restore checks that the target’s secret store is unsealed and that its unseal material is in place before it changes any data.
Section titled “Related documentation”