Team default secrets

When a new team is created (SUPERUSER provisioning, self-service signup, or the first-use default team), Delphi runs ensureTeamDefaults: it stamps platform-managed team secret variables, copies LLM API keys from platform secrets when values exist, and optionally creates a system WebRTC TelAPI key. Flow templates and the provider editor reference these keys as {{team.openaiDefaultKey}} and {{team.azureDefaultKey}}.

This page is for platform operators and SUPERUSERs setting up a deployment. Tenant team admins see the resulting variables only indirectly (see Visibility).

Operator prerequisite — platform secrets must exist

Autopopulate creates the team variable rows regardless, but copies a secret value only when the matching platform secret is registered and has a value in AWS Secrets Manager.

Platform secret key	Purpose in TelWeb	Required for
openaiDefaultKey	LLM API key (general collection)	Copying OpenAI credentials to every eligible new team. Without it, teams get an empty openaiDefaultKey variable and flows referencing {{team.openaiDefaultKey}} fail at runtime.
azureDefaultKey	Azure API key (general collection)	Copying Azure credentials on plans that include Azure (see By subscription tier).

Setup checklist (SUPERUSER)

1. Open Admin Settings → Platform Settings.
2. Under Secret storage, set AWS Region, Namespace, and General secrets collection (defaults are fine on a fresh install). Use Test Connection before saving in production.
3. In Platform Secrets at the bottom of the tab, Create each key:
   • Key: openaiDefaultKey, Purpose: LLM API key
   • Key: azureDefaultKey, Purpose: Azure API key (needed for tiers that receive Azure defaults)
4. For each row, click Set Secret and paste the provider API key. Values are stored in Secrets Manager under the general collection path — they are never shown again in TelWeb.
5. Create a test team (or run Backfill existing teams) and confirm flows can call OpenAI/Azure.

TLS trunk materials (TLS_CA_CERT, etc.) use a separate collection and are unrelated to LLM autopopulate — see Platform TLS materials.

Other platform secrets (briefingAiKey, scoringAiKey, signozApiKey, …) power platform-wide features (Flow Builder, QA, SigNoz) and are not copied to teams by this mechanism.

What gets provisioned per team

Artifact	Team variable / API key	When	Value source
OpenAI default key	SECRET variable openaiDefaultKey (superuserManaged)	Every plan tier	Copied from platform secret openaiDefaultKey when set
Azure default key	SECRET variable azureDefaultKey (superuserManaged)	Tiers above OpenAI-only (see below)	Copied from platform secret azureDefaultKey when set
WebRTC TelAPI key	TeamApiKey System WebRTC Call Token Key + SECRET webrtcTelapiKey	When FEATURE_API_ACCESS is on	Generated by the platform (not copied from a platform secret)

Side effects on first provision:

• Team awsSecretsKey is set to {namespace}/teams/{team-slug}/secrets (or {ENVIRONMENT}/teams/... when ENVIRONMENT / OTEL_DEPLOYMENT_ENVIRONMENT is set on the deployment).
• CREATE_CALL_TOKEN is added to the team's allowed API scopes when a WebRTC key is created.
• System WebRTC keys are systemManaged — they do not count toward customer API-key limits.

⚑Feature required: webrtc

This feature is gated. Operators enable it per deployment in the Delphi Portal; if the flag is off, the surface described below is hidden from the UI and rejected by the API. See Feature flags for the full registry.

WebRTC keys are only useful when the webrtc flag is also on (TelAPI session routes, Janus, browser voice). With FEATURE_API_ACCESS=false, TelAPI client routes are disabled and WebRTC key provisioning is skipped entirely.

By subscription tier

Tier logic is fixed in the platform (getPlatformManagedTeamSecretsForPlan):

Plan tier (slug)	openaiDefaultKey	azureDefaultKey
Starter, Business Small, Business Mid (starter, business_sml, business_mid)	Provisioned	Not provisioned
Custom, Unlimited / internal, and other non–OpenAI-only plans	Provisioned	Provisioned

If a team upgrades to a plan that adds Azure, ensureTeamDefaults runs again and creates azureDefaultKey when missing (copied from the platform secret if present). Downgrades schedule at period end and do not remove existing team secrets automatically.

When provisioning runs

Trigger	Behaviour
Team create (admin UI or signup)	ensureTeamDefaults after the team row and default subscription exist
First-use default team (delphi-setup)	Same defaults for the seeded team
Subscription upgrade (immediate plan change)	Re-runs defaults so newly eligible secrets (e.g. Azure) are added
delphi-setup --apply-missing step update.backfill-team-defaults	Backfills all existing teams (idempotent)

Existing team secret values are not overwritten on backfill if the team variable already holds a value in Secrets Manager — the step ensures rows, scopes, and missing keys exist.

Visibility

Role	What they see
Team ADMIN / MEMBER	Platform-managed variables (openaiDefaultKey, azureDefaultKey, webrtcTelapiKey) are hidden from the Variables tab.
SUPERUSER	Full variable list including superuser-managed entries; can Set Secret to override a team value if needed.

Published flows still reference {{team.openaiDefaultKey}} — tenants do not need to create those keys manually when autopopulate succeeded.

Backfill existing teams

Deployments that predated team defaults should run:

cd /opt/services/ops
./delphi-setup.sh --apply-missing

The registry step update.backfill-team-defaults calls backfillAllTeamDefaults for every team. Ensure platform secrets are set before backfill so copied values land on the first run.

Advanced: the API package ships backfill-team-defaults-and-egress for combined defaults + egress fallback wiring (see v0.9.13-patch1 release notes).

Troubleshooting

Symptom	Likely cause	Fix
New team flows fail on OpenAI auth	Platform secret openaiDefaultKey missing or empty	Create platform secret + Set Secret; SUPERUSER Set Secret on team variable or re-run backfill
Azure providers fail on higher tiers only	azureDefaultKey platform secret missing, or team still on OpenAI-only plan	Add platform secret; upgrade plan or run ensureTeamDefaults after upgrade
WebRTC test call / browser SDK 403	FEATURE_API_ACCESS or webrtc off; or no system WebRTC key	Enable flags; create team after flags on, or backfill
Team secret path errors in logs	ENVIRONMENT unset in production	Set ENVIRONMENT (or OTEL_DEPLOYMENT_ENVIRONMENT) on API/Voice hosts; confirm Secret storage namespace in Platform Settings
Variable exists but flow still empty	Copy skipped because platform secret had no value at provision time	Set platform secret value; SUPERUSER updates team secret or delete variable and re-run backfill

See also

• Platform settings — secret storage paths and Platform Secrets grid
• Platform TLS materials — SIP mTLS PEMs (separate from LLM keys)
• Configuration overview — boot-time vs runtime configuration sources
• Team overview — per-team Secrets Manager path
• Variables and secrets — tenant-managed variables
• Browser & SDK API — what the system WebRTC TelAPI key is used for
• Feature flags — webrtc and FEATURE_API_ACCESS