Secret
Alchemy provides built-in mechanisms for handling sensitive data securely. This guide explains how to manage secrets in your Alchemy resources.
What are Secrets?
Section titled “What are Secrets?”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
Encryption Password
Section titled “Encryption Password”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,});
Using the alchemy.secret() Function
Section titled “Using the alchemy.secret() Function”The primary way to handle secrets in Alchemy is with the alchemy.secret()
function:
// Create a secret from an environment variableconst apiKey = alchemy.secret(process.env.API_KEY);
When a secret is stored in state, it is automatically encrypted:
{ "props": { "key": { "@secret": "Tgz3e/WAscu4U1oanm5S4YXH..." } }}
Multiple Secret Values
Section titled “Multiple Secret Values”You can create multiple secrets in your application:
// Create multiple secrets from environment variablesconst apiKey = alchemy.secret(process.env.API_KEY);const databaseUrl = alchemy.secret(process.env.DATABASE_URL);const jwtSecret = alchemy.secret(process.env.JWT_SECRET);
Using Secrets in Resources
Section titled “Using Secrets in Resources”Secrets can be passed to resources like Cloudflare Workers. First, define your worker script:
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 secretsconst 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) }});