Skip to content
GitHubXDiscord

Secret

Alchemy provides built-in mechanisms for handling sensitive data securely. This guide explains how to manage secrets in your Alchemy resources.

Secrets in Alchemy are sensitive values that need special handling to prevent exposure in logs, state files, or source code. Examples include:

  • API keys and tokens
  • Passwords and credentials
  • Private certificates
  • Connection strings with credentials

Secrets are encrypted using a password that you provide when initializing your Alchemy app:

const app = await alchemy("my-app", {
stage: "dev",
password: process.env.SECRET_PASSPHRASE,
});

The primary way to handle secrets in Alchemy is with the alchemy.secret() function:

// Create a secret from an environment variable
const apiKey = alchemy.secret(process.env.API_KEY);

When a secret is stored in state, it is automatically encrypted:

{
"props": {
"key": {
"@secret": "Tgz3e/WAscu4U1oanm5S4YXH..."
}
}
}

You can create multiple secrets in your application:

// Create multiple secrets from environment variables
const apiKey = alchemy.secret(process.env.API_KEY);
const databaseUrl = alchemy.secret(process.env.DATABASE_URL);
const jwtSecret = alchemy.secret(process.env.JWT_SECRET);

Secrets can be passed to resources like Cloudflare Workers. First, define your worker script:

worker-script.ts
export default {
async fetch(request, env, ctx) {
const url = new URL(request.url);
if (url.pathname.startsWith('/env/')) {
const varName = url.pathname.split('/env/')[1];
const value = env[varName];
return new Response(value || 'undefined', {
status: 200,
headers: { 'Content-Type': 'text/plain' }
});
}
return new Response('Secret is safe: ' + env.API_KEY, { status: 200 });
}
};

Then use the script and bind the secrets:

// Use the script with secrets
const worker = await Worker("multi-secret-worker", {
name: "multi-secret-worker",
script: workerScript,
format: "esm",
bindings: {
API_KEY: alchemy.secret(process.env.API_KEY),
DATABASE_URL: alchemy.secret(process.env.DATABASE_URL),
JWT_SECRET: alchemy.secret(process.env.JWT_SECRET)
}
});