Environment Variables

Site vs Global Secrets — two stores, on purpose

There are two places a secret can live, matching the two kinds of functions:

Why two stores, and no automatic fallback? Two reasons. First, the same name often needs different values per site — an agency running three client sites has three different STRIPE_SECRET_KEYs, and a global-only store couldn't express that. Second, explicit beats clever with secrets: a site function can never silently read an account-wide key, and a global automation can never silently pick up some site's value. Each function reads exactly one store — the one matching its scope — so there are no surprises about which secret was used. If a value is genuinely needed in both worlds, you set it in both, deliberately.

The same split explains the two kinds of functions: site backend functions belong to one site — they run with that site's data, members, and secrets, and its pages call them. Account functions belong to you — they span sites (or need no site at all) and are triggered by webhooks, email triggers, and schedules. See Account Functions & Webhooks.

Site Variables — create & use

A site variable belongs to one site and is read by that site's backend functions — the functions its pages call. To create one:

1. Go to your app's Config tab in the dashboard
2. Scroll to the Environment Variables section
3. Enter a name (uppercase with underscores, e.g., STRIPE_SECRET_KEY)
4. Enter the value (your API key, secret, etc.)
5. Click Add

Then read it inside the site's backend functions with ctx.env.get(), which gives you the value as a string:

// Get an env var by name — ctx.env.get returns the value as a string
const value = await ctx.env.get('STRIPE_SECRET_KEY');

// A function can also WRITE its own config. Write-only, this site only, and
// the name must start with APP_ (so app code can never overwrite your keys).
await ctx.env.set('APP_ONBOARDING_STAGE', 'complete');

const result = await ctx.fetch('https://api.stripe.com/v1/charges', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${value}` },
  body: JSON.stringify({ amount: 1000, currency: 'usd' }),
});

Global Secrets — create & use

A global secret belongs to your whole account and is read by your account functions — the ones triggered by email triggers, webhooks, and schedules, which may have no site at all. To create one:

1. Go to Automations → Secrets in the dashboard (or just tell the AI: “save my Anthropic key as a global secret”)
2. Click Add secret, enter the name (e.g. ANTHROPIC_API_KEY) and paste the value
3. To change a value later, use the edit (pencil) action — adding a second secret with the same name is refused, so a working key is never replaced by accident

Account functions read it with exactly the same syntax site functions use for their own store:

// In an ACCOUNT function (e.g. one an email trigger runs):
const value = await ctx.env.get('ANTHROPIC_API_KEY');

// …or as a {{placeholder}} — resolved before the request is sent:
const res = await ctx.fetch('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: { 'x-api-key': '{{ANTHROPIC_API_KEY}}', 'anthropic-version': '2023-06-01' },
  body: JSON.stringify({ model: 'claude-sonnet-5', max_tokens: 300,
    messages: [{ role: 'user', content: 'Classify this email…' }] }),
});

// Account functions can also store their own state — code may only write
// APP_-prefixed names, so it can never overwrite your operator-set secrets:
await ctx.env.set('APP_LAST_SYNC_AT', new Date().toISOString());

Placeholder Syntax (both stores)

In any function — site or account — you can use {{VAR_NAME}} placeholders directly in ctx.fetch URLs, headers and bodies. They resolve from the function's own store (site variables in site functions, global secrets in account functions) before the request is sent. Only secrets ticked for that function are filled in; a name that is not ticked is sent as the literal text.

// Placeholders are resolved automatically
const result = await ctx.fetch('{{API_BASE_URL}}/users', {
  headers: {
    'Authorization': 'Bearer {{API_KEY}}',
    'X-Custom-Header': '{{CUSTOM_VALUE}}',
  },
});

From your site's pages (serverFetch)

Pages call serverFetch with the same placeholders. Because a visitor's browser chooses the address, a visitor's call fills in a secret only when the address's host is on that secret's Allowed hosts (Site Config → Environment Variables → Edit hosts), for example api.openai.com or *.example.com. With no hosts, visitors' calls that use the secret are refused. Your own preview is not limited, and tells you which host to add.

Where should a secret live?

The rule behind the whole table: code can never overwrite a secret a human set (function writes are limited to the APP_* namespace at both scopes), and the most protected stores are the ones where the value never enters code at all.