Intermediate
How to create custom variables and secrets on n8n
Quick Answer
Custom variables and secrets in n8n are created through the Settings menu by navigating to Environment Variables section. Variables store reusable values across workflows, while secrets store sensitive data like API keys securely.
Prerequisites
- n8n instance installed and running
- Admin access to n8n settings
- Basic understanding of n8n workflows
- Knowledge of environment variables
1
Access n8n Settings
Log into your n8n instance and click on Settings in the left sidebar menu. If you're using n8n cloud, ensure you have the necessary permissions to access environment variables. For self-hosted instances, make sure you're logged in as an admin user.
Tip
The Settings option is only visible to users with admin privileges in n8n.
2
Navigate to Environment Variables
In the Settings menu, locate and click on Environment Variables. This section allows you to manage both regular variables and secrets that can be used across all your workflows. You'll see a list of existing variables if any have been created previously.
3
Create a New Variable
Click the + Add Variable button to create a new environment variable. Enter a descriptive Name for your variable (e.g.,
API_BASE_URL or DEFAULT_EMAIL). In the Value field, input the actual value you want to store. Leave the Type as 'Variable' for non-sensitive data.Tip
Use uppercase with underscores for variable names following standard naming conventions.
4
Create a Secret Variable
To create a secret for sensitive data, click + Add Variable and enter your variable name (e.g.,
API_SECRET_KEY). Change the Type dropdown from 'Variable' to 'Secret'. Enter the sensitive value in the Value field. Secrets will be masked in the interface and encrypted in storage.Tip
Always use secrets for API keys, passwords, tokens, and other sensitive information.
5
Configure Variable Scope
Set the Scope for your variable by selecting either Global (available to all workflows) or Workflow-specific if targeting particular workflows. For most use cases, Global scope is recommended. Review your variable configuration and click Save to create it.
Tip
Global variables are more convenient but workflow-specific variables provide better organization for large projects.
6
Use Variables in Workflows
In your workflow nodes, reference your variables using the syntax
${{$env.VARIABLE_NAME}}. For example, to use an API key secret, enter ${{$env.API_SECRET_KEY}} in the authentication field of an HTTP Request node. The variable will be automatically resolved during workflow execution.Tip
Use the Expression Editor to easily insert environment variables with auto-completion.
7
Test and Validate Variables
Create a simple workflow with a Code node or HTTP Request node that uses your new variable. Execute the workflow to ensure the variable is properly resolved. Check the execution logs to verify the variable value is being used correctly (secrets will show as masked values).
Tip
Always test variables in a non-production workflow before using them in critical processes.
8
Manage and Update Variables
Return to Settings > Environment Variables to edit, delete, or add more variables as needed. Click the Edit icon next to any variable to modify its value or settings. Use the Delete option to remove unused variables. Changes take effect immediately across all workflows.
Tip
Document your variables and their purposes to maintain clarity in team environments.
Troubleshooting
Environment Variables menu is not visible in Settings
Ensure you have admin privileges in n8n. For self-hosted instances, check that your user account has the necessary permissions. In n8n cloud, verify your subscription plan includes environment variables feature.
Variable not resolving in workflow execution
Verify the variable name spelling matches exactly (case-sensitive). Ensure you're using the correct syntax
${{$env.VARIABLE_NAME}} and that the variable scope includes your current workflow.Cannot save or create new variables
Check your n8n instance has sufficient disk space and memory. For Docker installations, ensure the container has write permissions. Restart your n8n instance if the issue persists.
Secret values showing as undefined or empty
Ensure the secret was saved properly and contains a value. Check that your n8n version supports secrets (v0.190.0+). For self-hosted instances, verify the encryption key is properly configured in your environment.
Ready to get started with n8n?
Put this tutorial into practice. Visit n8n and follow the steps above.
Visit n8n →