Circuitry Logo
Circuitry
Open Editor

Environment Variables - Secure Configuration

Environment Variables are a secure way to store configuration values and sensitive information like API keys, database connection strings, and authentication tokens. They keep these secrets out of your code and away from version control, preventing security breaches and unauthorized access.

🔐 What Are Environment Variables?

Environment variables are key-value pairs that exist outside your application code. They provide:

  • Security: Keep sensitive data like API keys and passwords out of your codebase
  • Flexibility: Different values for development, staging, and production environments
  • Portability: Same code runs in different environments with different configurations
  • Protection: Prevent accidental exposure of secrets in git repositories

Why Use Environment Variables?

Instead of hardcoding sensitive values:

// ❌ Never do this!
const apiKey = "sk-1234567890abcdef";
const dbPassword = "mySecretPassword123";

Use environment variables:

// ✅ Safe and secure
const apiKey = process.env.API_KEY;
const dbPassword = process.env.DB_PASSWORD;

🚀 Setting Up Environment Variables

In Circuitry Settings

  1. Navigate to Settings in the top navigation
  2. Click on the Environment Variables tab
  3. Add your variables as key-value pairs
  4. Click Save to store them securely

Variable Format

Environment variables follow these conventions:

  • Names: Use UPPERCASE with underscores (e.g., API_KEY, DATABASE_URL)
  • Values: Can be strings, numbers, or URLs
  • No spaces: Don't use spaces in variable names

Common Examples

# API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/db

# Service URLs
API_BASE_URL=https://api.example.com
WEBHOOK_URL=https://yourapp.com/webhooks

# Authentication
AUTH_SECRET=your-secret-key-here
JWT_SECRET=your-jwt-secret
OAUTH_CLIENT_ID=123456789
OAUTH_CLIENT_SECRET=abcdef123456

# Feature Flags
ENABLE_DEBUG=true
MAX_RETRIES=3
TIMEOUT_SECONDS=30

💡 Using Environment Variables in Workflows

In Template Variables

Reference environment variables in any node using the {{env.VARIABLE_NAME}} syntax:

{{env.API_KEY}}
{{env.DATABASE_URL}}
{{env.WEBHOOK_SECRET}}

In Agent Nodes

Use environment variables in AI prompts:

You are connected to the database at {{env.DATABASE_URL}}.
Use the API key {{env.OPENAI_API_KEY}} for authentication.
The webhook endpoint is {{env.WEBHOOK_URL}}.

In Action Nodes

Configure HTTP requests with environment variables:

Headers:

{
  "Authorization": "Bearer {{env.API_TOKEN}}",
  "X-API-Key": "{{env.SERVICE_API_KEY}}"
}

URL:

{{env.API_BASE_URL}}/users/{{input.userId}}

In Code Nodes

Access environment variables in JavaScript:

// Environment variables are replaced before execution
const apiKey = "{{env.API_KEY}}";
const baseUrl = "{{env.API_BASE_URL}}";
const maxRetries = parseInt("{{env.MAX_RETRIES}}" || "3");

// Use them in your logic
const response = await fetch(`${baseUrl}/data`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

In Plugin Configurations

Plugins can use environment variables for authentication:

{
  "apiKey": "{{env.SLACK_API_KEY}}",
  "webhookUrl": "{{env.SLACK_WEBHOOK_URL}}"
}

🛡️ Security Best Practices

1. Never Commit Secrets

Never commit environment variables to version control:

  • Don't include .env files in git
  • Add .env to .gitignore
  • Use environment variable management in Circuitry

2. Use Descriptive Names

Clear naming prevents confusion:

# Good ✅
OPENAI_API_KEY=sk-...
STRIPE_WEBHOOK_SECRET=whsec_...
DATABASE_CONNECTION_STRING=...

# Bad ❌
KEY=sk-...
SECRET=whsec_...
DB=...

3. Separate by Environment

Use different variables for different environments:

# Development
DEV_API_URL=http://localhost:3000
DEV_DATABASE_URL=sqlite://./dev.db

# Production
PROD_API_URL=https://api.production.com
PROD_DATABASE_URL=postgresql://prod-server/db

4. Rotate Secrets Regularly

  • Change API keys periodically
  • Update passwords and tokens
  • Remove unused variables

5. Limit Access

  • Only share credentials with team members who need them
  • Use different keys for different team members when possible
  • Revoke access when team members leave

🔧 Managing Environment Variables

Adding Variables

  1. Go to Settings → Environment Variables
  2. Click Add Variable
  3. Enter the name (uppercase with underscores)
  4. Enter the value (will be encrypted)
  5. Click Save

Editing Variables

  1. Find the variable in your list
  2. Click the Edit button
  3. Update the value
  4. Click Save

Deleting Variables

  1. Find the variable to remove
  2. Click the Delete button
  3. Confirm deletion

Viewing Variables

  • Variable names are always visible
  • Values are hidden by default (shown as ••••••)
  • Click the eye icon to reveal a value temporarily

📚 Common Use Cases

API Integration

Store API credentials securely:

# Third-party APIs
OPENAI_API_KEY=sk-...
STRIPE_API_KEY=sk_live_...
TWILIO_AUTH_TOKEN=...
SENDGRID_API_KEY=SG....

# Internal APIs
INTERNAL_API_KEY=...
SERVICE_ACCOUNT_KEY=...

Database Connections

Keep database credentials safe:

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=dbuser
POSTGRES_PASSWORD=dbpass
POSTGRES_DB=myapp

# MongoDB
MONGO_URI=mongodb://user:pass@host:27017/db

OAuth Configuration

Store OAuth credentials:

# Google OAuth
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# GitHub OAuth
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

Feature Configuration

Control features and limits:

# Features
ENABLE_BETA_FEATURES=true
DEBUG_MODE=false
LOG_LEVEL=info

# Limits
MAX_UPLOAD_SIZE=10485760
RATE_LIMIT=100
TIMEOUT_MS=30000

🐛 Troubleshooting

Variable Not Found

If {{env.VARIABLE_NAME}} isn't working:

  1. Check the variable exists in Settings
  2. Verify the exact spelling (case-sensitive)
  3. Make sure the variable is saved
  4. Refresh the workflow editor

Value Not Updating

If changes aren't reflected:

  1. Save the environment variable
  2. Refresh the workflow
  3. Re-run the workflow

Special Characters

If values with special characters cause issues:

  • Wrap values in quotes if needed
  • Escape special characters with backslash
  • Use URL encoding for URLs with special characters

🎯 Tips and Tricks

1. Group Related Variables

Use prefixes to organize:

# Database variables
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp

# API variables
API_KEY=...
API_SECRET=...
API_BASE_URL=...

2. Document Your Variables

Keep a secure record of:

  • What each variable is for
  • Where it's used
  • Who has access
  • When to rotate

3. Use Fallback Values

In Code nodes, provide defaults:

const apiUrl = "{{env.API_URL}}" || "https://api.default.com";
const retries = parseInt("{{env.MAX_RETRIES}}" || "3");

4. Test with Different Values

  • Use test API keys for development
  • Use sandbox environments when available
  • Never use production credentials in testing

🔗 Related Documentation