n8n API Key Setup: Credentials, Environment Variables, and Security (2026)

In n8n, the word "key" covers at least three different things: the public API key that manages the n8n instance, the OpenAI-compatible key that calls model services, and N8N_ENCRYPTION_KEY, which protects the credentials stored in the database. They serve different purposes, and putting one in the wrong place creates security problems. Many "my configuration does not work" requests turn out to be one of these keys mistaken for another.

This article follows the order of what each key is, where it belongs, how to rotate it, and how to troubleshoot it. It is aimed at self-hosting teams and instances shared by multiple people.

Note: n8n is a trademark of n8n GmbH, and OpenAI is a trademark of OpenAI, Inc. This article is technical guidance only and implies no affiliation or partnership with those companies. Prices and available models are subject to the in-site model pricing page.

1. Tell the three keys apart

Type	Purpose	Where it lives	Typical request header
n8n public API key	Calls n8n's own REST API to manage workflows and executions	Created in the n8n UI, stored by the caller	`X-N8N-API-KEY`
Model service key	Calls an OpenAI-compatible endpoint	n8n credential, encrypted at rest	`Authorization: Bearer ...`
`N8N_ENCRYPTION_KEY`	Encrypts credentials in the database	Environment variable or `.n8n` configuration file	Never sent as a header

A public API key cannot call models, and a model key cannot manage n8n workflows. The most direct consequence of mixing them up is a 401, or an expansion of permissions that should have been read-only.

2. Creating the n8n public API key

The entry point is Settings > n8n API. Click Create an API key, then fill in a Label and an expiration time. The official documentation notes that the public API is unavailable during the cloud free trial; on Enterprise, you can also choose Scopes to restrict a key to specific resources and actions such as workflow:read or credential:list. Keys outside Enterprise have full access to account resources by default, so controlling who holds them matters even more.

Pass the key in the X-N8N-API-KEY header when calling the API; paths usually start with /api/v1:

curl -sS "https://your-n8n-domain/api/v1/workflows?active=true" \
  -H "accept: application/json" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

A few rules:

One key serves one purpose, such as CI, monitoring, or an internal tool.
Set an expiration date and rotate proactively before it lapses.
Never put the key in frontend code, URL parameters, or logs.
Do not use a public API key as a substitute for a model key.
Disable the public API with N8N_PUBLIC_API_DISABLED=true when you do not need it.

3. Model credentials: keys belong in credentials

To connect to an OpenAI-compatible service, use an OpenAI-type credential and enter the API key and Base URL. The gateway address usually ends at /v1, for example https://ai.zhongshangqihang.com/v1. Organization ID is only needed for official OpenAI accounts that belong to multiple organizations; with a compatible gateway it is normally left blank. Credentials also support additional custom headers, which helps when a gateway requires an extra identifier.

Never let the key appear in these places:

Code nodes, Set nodes, or prompts;
ordinary fields in the workflow JSON;
webhook responses, execution logs, or error notifications;
screenshots, screen recordings, or shared documents.

Workflow exports normally exclude the credentials themselves, but a key written into node parameters travels with the JSON. Before sharing a workflow with the team, search it for sk- and other common key prefixes.

4. Environment variables: fine for configuration, not a secret store

Self-hosted n8n uses environment variables to configure ports, databases, webhook addresses, and more. Sensitive values such as N8N_ENCRYPTION_KEY and database passwords should also be injected through environment variables or a secrets manager, not written into a Compose file committed to Git. Some variables support a _FILE suffix, which reads the value from a separate file.

Environment variables are not a secure secret store, however. The n8n documentation explicitly warns that environment variables are not protected within n8n and may be exposed to users. That is why bulk-distributing credentials with CREDENTIALS_OVERWRITE_DATA is not recommended; an authenticated overwrite endpoint is the safer route.

If business users are allowed to edit workflows, consider enabling N8N_BLOCK_ENV_ACCESS_IN_NODE=true to stop expressions and Code nodes from reading environment variables. The variable defaults to false, and changing it requires an instance restart. Note also that execution history stores node inputs and outputs; redact sensitive fields before they enter n8n, or shorten retention with EXECUTIONS_DATA_MAX_AGE.

5. The encryption key: lose it and every credential is unreadable

On first startup, n8n generates an encryption key automatically, stores it in the ~/.n8n directory, and uses it to encrypt credentials before writing them to the database. You can also set a custom value through N8N_ENCRYPTION_KEY. The official documentation states plainly that if this key is lost, all saved credentials become unreadable.

Backups therefore need to be done in pairs: store the database backup and the encryption key separately, with separate access controls. A database-only backup cannot decrypt credentials after restore without the original key; a key-only backup is meaningless if the database is gone.

In queue mode, the main instance and every worker must use the same N8N_ENCRYPTION_KEY, otherwise workers cannot decrypt credentials written by the main instance. Put this on the deployment checklist before scaling out.

As of n8n 3.0, encryption key rotation is supported by default; 2.x requires manually enabling N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true and keeping it consistent across all nodes. Take a full database backup before rotating; the official documentation also warns against downgrading to an older version after enabling the new format. The rotation entry point is Settings > Data Encryption Keys.

6. Rotation and least privilege

Key management is not a one-time setup; it is a continuous tightening of permissions:

By environment: separate keys for development, testing, and production; production keys never live on a developer machine.
By project: one key per project, so usage and quotas can be observed separately.
By person: each person has their own key, revoked individually on departure; avoid shared keys for everyone.
Short expiry: set expiration dates on public API keys, and rotate model keys periodically as well.
Create before delete: during rotation, create the new key, update the caller, verify it works, then revoke the old key.
Least privilege: on Enterprise, select only the necessary scopes for public API keys; grant project roles only the permissions they need.
Restrict usage: some Web API-based credentials can limit the allowed HTTP request domains, reducing the risk of a key being used against other addresses.
Audit: keep records of key creation, use, and deletion, and alert on abnormal usage promptly.

Instance roles in n8n include Owner, Admin, and Member, and projects and credentials can be isolated by project. On the Community edition, credentials live in personal spaces; versions that support projects can place credentials in a project for its members to use. Custom roles and fine-grained enterprise permissions are Enterprise capabilities; check the official documentation for the exact scope.

Practical recommendations:

Keep the number of Owners small and use Admin or Member for daily work.
Put business workflows in projects, and credentials in those same projects rather than personal spaces.
Name credentials consistently as "service-environment-purpose", for example "gateway-prod-support-summary".
Do not share login accounts, and do not send personal keys to colleagues.
Enable MFA, enforce HTTPS on production instances, and set N8N_SECURE_COOKIE=true.
Use an external task runner in production; the official documentation marks internal mode as not recommended and deprecates it as of 3.0.

Enterprise editions can also use external secret stores, referencing values from 1Password Connect, AWS Secrets Manager, Azure Key Vault, GCP Secrets Manager, HashiCorp Vault, or Infisical in credential fields. A reference resolves only within that field and does not appear in other workflow expressions.

8. Common troubleshooting

Symptom	Possible cause	What to do
Credentials cannot be decrypted	`N8N_ENCRYPTION_KEY` was changed, or an old database was restored	Restore the original key; restore from a matching backup
Public API returns 401	Missing or expired `X-N8N-API-KEY`	Create a new key and check the request header
Public API returns 403	Insufficient Enterprise scopes	Add the required scope such as `workflow:read`
Model request returns 401	Model key wrong, expired, or credential not selected	Re-enter the key and confirm the credential is bound to the node
Environment variable not visible	Variable not passed into the container, or node access disabled	Check the Compose environment and `N8N_BLOCK_ENV_ACCESS_IN_NODE`
Worker reports decryption failure	Worker and main instance keys differ	Unify `N8N_ENCRYPTION_KEY` and restart

Start troubleshooting from "what changed recently": swapping keys, changing the Base URL, upgrading versions, and migrating databases are the four changes most likely to cause key problems. Change one variable at a time and verify immediately with the smallest possible request.

FAQ

Is an n8n API key the same as an OpenAI API key?

No. The n8n API key calls n8n's own REST API and goes in the X-N8N-API-KEY header; an OpenAI-compatible key calls model endpoints, lives in a credential, and is sent by the node as a Bearer token.

Do n8n public API keys support permission scopes?

On Enterprise, yes: scopes can restrict a key to specific resources and actions, and the guidance is to grant only what is needed. Keys outside Enterprise have full access to account resources by default, so split them by person and purpose and set expiration dates.

What happens if I change `N8N_ENCRYPTION_KEY`?

Credentials already encrypted and stored usually cannot be decrypted anymore. Fix the value at first deployment and back it up. If it must change, first assess whether the official key rotation feature can do the job; do not simply edit the environment variable.

Can I put keys in environment variables for workflows to use?

You can, but it is not recommended. The n8n documentation warns that environment variables are not protected and may be exposed to users. Credentials or an external secret store are safer. If environment variables are unavoidable, at least enable N8N_BLOCK_ENV_ACCESS_IN_NODE and restrict access to the instance.

Not recommended. A shared key makes usage impossible to attribute, exposes everyone when one person leaks it, and cannot be revoked individually. Split keys by project, environment, or person, and pair them with gateway quotas and usage reports for better cost and security control.

Next steps

The n8n key system can be summarized in one sentence: public API keys manage the instance, model keys manage calls, and the encryption key manages the database. Store them separately, rotate them separately, and add project roles, expiration dates, and auditing to complete the setup. For a unified model entry point and usage management, sign up for ZSQH AI Gateway; models and prices are subject to the model pricing page.