encore-secret

Encore Secrets

Instructions

Secrets are encrypted, environment-scoped values managed by Encore. Declare them at package level by calling secret(name) and read them by calling the returned function.

import { secret } from "encore.dev/config";

// Package-level declaration
const stripeKey = secret("StripeSecretKey");

// Read inside a handler
async function chargeCustomer() {
  const key = stripeKey();        // <-- function call returns the value
  const stripe = new Stripe(key);
  // ...
}

Secret names are globally unique across the application (the same name resolves to the same value everywhere).

Setting values

# Set per environment type
encore secret set --type prod StripeSecretKey
encore secret set --type dev StripeSecretKey
encore secret set --type local StripeSecretKey

Environment types: production (alias prod), development (alias dev), preview (alias pr), local.

Local overrides

For local development without going through encore secret set, create a .secrets.local.cue file at the repo root (gitignore it):

StripeSecretKey: "sk_test_local_..."
GitHubAPIToken:  "ghp_local_..."

Common usage patterns

// HTTP headers
const githubToken = secret("GitHubAPIToken");
const resp = await fetch("https://api.github.com/user", {
  headers: { Authorization: `token ${githubToken()}` },
});

// Webhook signature verification
const stripeWebhookSecret = secret("StripeWebhookSecret");
stripe.webhooks.constructEvent(rawBody, sig, stripeWebhookSecret());

// Connecting to a third-party SDK
const openaiKey = secret("OpenAIKey");
const openai = new OpenAI({ apiKey: openaiKey() });

Guidelines

• Always declare secret(...) at package level, never inside functions.
• Read with a function call: stripeKey() not stripeKey.
• Set distinct values per environment via encore secret set --type <env>.
• Never commit secret values; use .secrets.local.cue for local overrides and gitignore it.
• For webhook signature secrets specifically, see also the encore-webhook skill.