The n8n API key: create, use, secure and revoke access to your instance

Search for "n8n api key" and you will mostly find partial answers: where to click, but rarely what the key actually grants, or how to manage it over time. Yet that is the sensitive part: an n8n API key gives full programmatic access to your instance — workflows, executions, credentials, and users depending on the edition. This guide covers the key's entire lifecycle: creating it, understanding its exact scope, using it properly (the X-N8N-API-KEY header), storing it, rotating it, revoking it — and switching the public API off entirely if you don't use it.

What an n8n API key is for

The API key is the entry point to n8n's public API, the one that administers the instance programmatically: exporting workflows for backup, activating or deactivating them in bulk, reading execution history, provisioning credentials, and — depending on the edition — managing users. Everything that feeds a CI/CD pipeline or an operations script goes through it.

Driving n8n through its REST API — endpoints, pagination, detailed use cases — has its own guide. Here we focus on the key itself: it is where the risk concentrates.

Creating the key: Settings → n8n API

1. Log in to your instance with the account that will carry the key (we come back to this right after — the choice matters);
2. Open Settings, then the n8n API section;
3. Click Create an API key. Depending on the version, you can label the key — always do it ("nightly-backup", "ci-github") — and set a validity period;
4. Copy the key immediately: it is displayed exactly once. If you lose it, you will have to delete it and generate a new one.

Where the copy-paste goes: a secrets manager (Vault, Bitwarden, your cloud provider's secret manager) or an environment variable on the server side — never a notes file, never a Slack channel, never a commit.

The key's scope: it acts as you, with no nuance

This is the most misunderstood point. An n8n API key acts on behalf of the account that created it, with all of that account's rights: on most instances there is no "read-only" or "limited to this workflow" granularity — a single permission level, the account's. A key created by the owner or an admin can therefore read, modify, delete or deactivate every workflow, and manipulate credentials. On a multi-user instance, the simplest way to limit a key is to create it from a member account with restricted rights — our guide to users and permissions on self-hosted n8n details the roles. Otherwise, treat it as an administrator-level secret, because that is what it is.

Using the key: the X-N8N-API-KEY header

Every request to the public API goes through the /api/v1 prefix and carries the key in a dedicated header, X-N8N-API-KEY. The simplest test, from a terminal:

export N8N_API_KEY="your-key"  # in practice: from your secrets manager

curl -s "https://n8n.example.com/api/v1/workflows?active=true" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

If the response is a JSON list of your active workflows, the key works. A 401 error means the key is missing, misspelled in the header, or revoked.

From an n8n workflow itself (yes, an instance can self-administer), use an HTTP Request node with a Header Auth credential: header name X-N8N-API-KEY, value the key. The credential is encrypted at rest, whereas a key pasted directly into a node parameter would leave in cleartext with every export of that workflow. For an external script, same logic: the key lives in an environment variable, and the code only knows its name.

Self-hosted or Cloud: who gets the API?

On a self-hosted instance, the public API is included, with no extra cost or restriction. On n8n Cloud, API availability depends on the plan — and since conditions change, check whether the n8n API section appears in your Settings and consult the current pricing page. If the API is a structural need (CI/CD, automated backup), factor that criterion into your plan choice from day one.

Securing it: one key per use, rotation, revocation

Key leaks are not a theoretical risk. The study by Michael Meli, Matthew McNiece and Bradley Reaves, "How Bad Can It Git? Characterizing Secret Leakage in Public GitHub Repositories", presented at NDSS in 2019 (see on Google Scholar), scanned public GitHub commits in real time for nearly six months: thousands of unique secrets — API keys, tokens, cryptographic keys — leak every single day, and more than 100,000 repositories contained at least one. The dominant cause is not a sophisticated attack; it is the ordinary commit of a config file or an export that should never have been versioned.

Applied to n8n, that gives four rules:

• One key per use. One for backup, one for monitoring, one for CI. The day one leaks or becomes useless, you revoke it without breaking the rest — and the label tells you immediately what is exposed;
• Storage outside the code. Secrets manager or environment variable, never hardcoded in a script, and above all never in a node parameter of a workflow you version in Git: a workflow's JSON export embeds parameter values, not credential values. The same reflexes as for securing API credentials;
• Scheduled rotation. Create the new key, switch the consumers over, delete the old one. Do it on a fixed schedule for permanent keys, and immediately when a team member who had access leaves;
• Immediate revocation at the slightest doubt. Settings → n8n API → delete: the effect is instantaneous. Revoke first, investigate second.

Not using the API? Disable it

A door nobody walks through doesn't need to exist. If no script, no CI and no external tool calls your public API, switch it off with an instance-level environment variable:

N8N_PUBLIC_API_DISABLED=true

The web interface and webhooks keep working normally; only the /api/v1 endpoints disappear. It is a free attack-surface reduction — re-enabled in thirty seconds the day a real need shows up.

API key, credentials, webhook: three objects, three roles

The confusion is common, and it gets expensive when it leads to exposing the wrong privilege level:

• The n8n API key authenticates a call to the instance's administration. Maximum scope — protect it like root access;
• Credentials store the secrets your workflows use towards third-party services (Google, Stripe, OpenAI…). Encrypted at rest, never included in workflow exports;
• A webhook is an entry point to a single workflow: its scope is limited to what that workflow does, and its authentication is configured node by node — our complete webhook guide covers the topic.

Practical rule: if a third-party system needs to trigger a process, give it a webhook. The API key never leaves the circle of administration tooling.

Three use cases that justify a key

• Nightly backup to Git. A script (or a scheduled workflow) calls /api/v1/workflows, writes one JSON file per workflow and commits the changes. The format is the same as a manual workflow export, but it depends on nobody. Dedicated "backup" key, created from an account with minimal rights;
• Dev → prod deployment. The pipeline fetches the workflow from the dev instance, remaps credential IDs, pushes it to prod and activates it. Two distinct keys, one per instance, stored in the CI's secrets — see our guides on dev and prod environments and validating n8n workflows in CI with GitHub Actions;
• Inventory of active workflows. A call filtered on active=true feeds a dashboard or a weekly report: what actually runs, owned by whom, since when. On an instance that grew organically, it is often the first surprise.

Key takeaways

An n8n API key takes thirty seconds to create in Settings → n8n API, but it commits you to much more: it acts on behalf of the account that created it, with a single permission level, and opens full instance administration through the X-N8N-API-KEY header. The healthy lifecycle fits in one sentence: one labelled key per use, stored in a secrets manager or an environment variable, rotated on a fixed schedule, revoked without hesitation — and an API switched off outright (N8N_PUBLIC_API_DISABLED=true) as long as nobody uses it.