Secrets & env

Source code may only contain secret names. Values live in the project vault / environment and resolve at runtime inside workflows — never in the browser.

1. Declare names

File: .appbricx/backend/secrets.refs.json

[
  "WEBHOOK_SECRET",
  "LEAD_NOTIFY_URL",
  "DIGEST_EMAIL",
  "SLACK_BOT_TOKEN"
]

The agent appends names when it wires webhooks or integrations. Dedupe the array; do not store values here.

2. Set values

Project Settings → Environment / Secrets (vault UI).
Map each name to a value for the environment you care about (preview/production as offered).
For webhooks, the value of secret_ref must match what callers send in x-appbricx-webhook-secret.

3. Use in workflows

export async function run(ctx) {
  const secret = await ctx.secrets.get("WEBHOOK_SECRET");
  // returns null if unset or not listed in secrets.refs.json

  const notifyUrl = await ctx.secrets.get("LEAD_NOTIFY_URL");
  if (notifyUrl) {
    await ctx.http.fetch(notifyUrl, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ event: "leads.created" }),
    });
  }
}

4. Use in webhook manifests

{
  "name": "lead-intake",
  "workflow": "on-lead-created",
  "secret_ref": "WEBHOOK_SECRET",
  "enabled": true
}

Managing day to day

Task	Where
Add a new secret name	Edit `secrets.refs.json` (or ask the agent)
Rotate a value	Vault UI — update value; no code change
Remove a secret	Clear vault value; remove refs + `secret_ref` usages
BYOK provider keys	Separate — AI settings, not workflow refs

Anti-patterns

const KEY = "sk_live_…" in any project file
Committing .env with real credentials
Putting the webhook secret string inside webhooks/*.json
Sending secrets to the browser / runtime client

Validate. Ask the agent to run runtime.validate — it checks refs exist and scans backend files for obvious literal secrets.

Related: Webhooks · Workflows · Data templates

3. Use in workflows

export async function run(ctx) { const secret = await ctx.secrets.get("WEBHOOK_SECRET"); // returns null if unset or not listed in secrets.refs.json const notifyUrl = await ctx.secrets.get("LEAD_NOTIFY_URL"); if (notifyUrl) { await ctx.http.fetch(notifyUrl, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ event: "leads.created" }), }); } }

Task

Where

Add a new secret name

Edit secrets.refs.json (or ask the agent)

Rotate a value

Vault UI — update value; no code change

Remove a secret

Clear vault value; remove refs + secret_ref usages

BYOK provider keys

Separate — AI settings, not workflow refs

Anti-patterns

const KEY = "sk_live_…" in any project file

Committing .env with real credentials

Putting the webhook secret string inside webhooks/*.json

Sending secrets to the browser / runtime client

Validate. Ask the agent to run runtime.validate — it checks refs exist and scans backend files for obvious literal secrets.