n8n API Guide 2026: Authentication, Endpoints & Examples

TL;DR: n8n exposes a JSON REST API for managing workflows, executions, credentials, users, tags, variables and projects. Authenticate with an API key sent in the X-N8N-API-KEY header. The same API is identical on Community (self-hosted, free), Cloud, and Enterprise — only enterprise adds scope-limited keys and SSO-managed users.

What is the n8n API?

n8n is an open-source workflow automation platform — a Zapier and Make alternative that runs as a Node.js application you can self-host or buy as a managed cloud service. The public REST API sits on top of that platform and lets external systems do everything the n8n web UI does, except via HTTP.

Teams use the API for four main jobs. First, infrastructure-as-code: storing workflows as JSON in Git and deploying them from CI/CD into staging and production n8n instances. Second, programmatic execution: triggering a workflow from a backend service when a webhook is the wrong primitive (for example, because the caller needs an execution ID returned synchronously). Third, observability: pulling execution data into Datadog, Snowflake, or a custom dashboard for SLA monitoring. Fourth, multi-tenancy: dynamically creating per-customer workflows in a SaaS product that white-labels n8n as its automation backend.

Almost everything in this guide applies equally to Community (self-hosted) and Cloud editions. The only meaningful divergence is scopes — Enterprise lets you restrict an API key to a subset of resources and actions, while Community and standard Cloud keys are full-access. Walk through the full n8n review for a complete platform tour; this guide is the developer-side companion.

Authentication: the X-N8N-API-KEY header

n8n authenticates every API request with a long-lived API key sent in a request header. There is no OAuth flow, no signed timestamps, no HMAC — by design, it is the simplest possible scheme so teams can integrate quickly. The trade-off is that you must treat each key like a password, store it in a secrets manager, and rotate it on schedule.

Step 1 — Generate the key

Log into your n8n instance, open the user menu in the bottom-left corner, and select Settings → n8n API. Click Create an API key. Give it a Label (something like "ci-deploy" or "datadog-poller") and an Expiration. If you are on Enterprise, you can also tick Scopes to limit access.

n8n shows the raw key exactly once. Copy it immediately into your secrets manager — there is no way to retrieve it afterwards. If you lose it, you generate a replacement and delete the old one.

Step 2 — Send the header

Every API request must include the header X-N8N-API-KEY: <your-key>. The header name is case-insensitive but exact spelling matters. Requests without the header return 401 Unauthorized with a JSON error body. Requests with a malformed or expired key return the same 401.

cURL example:

curl -X GET "https://your-instance.app.n8n.cloud/api/v1/workflows" \
  -H "X-N8N-API-KEY: n8n_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Node.js (fetch) example:

const res = await fetch('https://your-instance.app.n8n.cloud/api/v1/workflows', {
  headers: {
    'X-N8N-API-KEY': process.env.N8N_API_KEY,
    'Accept': 'application/json'
  }
});
const { data, nextCursor } = await res.json();

Step 3 — Rotate on a schedule

Set the expiration to 90 days, not "never". A rotated key that has expired but wasn't yet replaced fails closed (returns 401) — a leaked key that never expires fails open. The Enterprise scopes feature is essentially a way to limit the blast radius of a leak, which is why it exists. For most teams, two operational keys (one in CI, one in production observability) covers 90% of use cases without needing scopes at all.

Base URL and versioning

Every endpoint lives under /api/v1/ on your n8n instance. The version prefix has been v1 since the API graduated from preview in 2022 and n8n has committed to backwards-compatibility within v1 — they have added endpoints but not removed or breaking-changed any. Your full base URL depends on deployment:

• n8n Cloud: https://<your-subdomain>.app.n8n.cloud/api/v1
• Self-hosted (default port): http://localhost:5678/api/v1
• Self-hosted (behind a reverse proxy): https://n8n.your-domain.com/api/v1

If you front your self-hosted instance with Nginx or Caddy, make sure the proxy passes the X-N8N-API-KEY header through unchanged. The single most common "API doesn't work" support ticket is a misconfigured reverse proxy stripping headers.

The endpoint surface

The public API covers seven resource families. Below is the full list with what each is for in practice.

Workflows

The most-used endpoints. GET /workflows lists workflows with pagination; POST /workflows creates a workflow from JSON; GET /workflows/{id} retrieves one with its full node graph; PUT /workflows/{id} replaces it; DELETE /workflows/{id} removes it; POST /workflows/{id}/activate and /deactivate toggle the trigger schedule.

The tags query parameter on GET /workflows filters by tag — useful in CI to deploy only workflows tagged prod. Pagination uses limit (max 250) and cursor from the previous page's response. Always paginate; loading 5,000 workflows in a single call will time out the connection.

Executions

GET /executions lists historical executions with filters for workflowId, status (success, error, waiting) and date ranges. GET /executions/{id} returns the full execution data including each node's input and output payload. DELETE /executions/{id} removes one. There is no API endpoint to start an execution synchronously — that uses the workflow's webhook URL, which is a different surface area (a long-standing complaint on GitHub).

Credentials

POST /credentials creates a credential (an OAuth token, API key, or DB connection string) without exposing it in plaintext to your CI logs. GET /credentials/schema/{credentialTypeName} returns the JSON schema for a credential type so you know which fields to populate. There is intentionally no endpoint to read credential secrets back — once stored, they can only be used, not retrieved.

Users (admin only)

On Cloud Enterprise and self-hosted Enterprise, GET /users, POST /users, GET /users/{id} and DELETE /users/{id} let you provision and de-provision users via SCIM-style flows. Community and standard Cloud only expose the read endpoints because user management is single-tenant by default.

Tags, variables, projects

Tags (/tags) organize workflows. Variables (/variables) store environment-style config values that the $vars expression in any workflow node can read. Projects (/projects) are the Enterprise feature that groups workflows into team-owned namespaces with shared credentials. All three follow the same CRUD pattern as the others.

Source control

If your Enterprise instance is connected to GitHub or GitLab, POST /source-control/pull and POST /source-control/push let you trigger Git operations from outside the UI. This is how teams that prefer GitOps-style workflow deployment automate the round-trip.

Common API patterns: 6 code examples that solve real problems

1. List all active workflows in a project

curl "$BASE/workflows?active=true&projectId=$PROJECT_ID&limit=100" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

2. Export a workflow to a JSON file (the version-control workflow)

curl "$BASE/workflows/$WORKFLOW_ID" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  | jq '.' > workflows/customer-onboarding.json

3. Promote a workflow from staging to prod (the deploy step)

# From a GitHub Actions step on push to main
curl -X POST "$PROD_BASE/workflows" \
  -H "X-N8N-API-KEY: $N8N_PROD_API_KEY" \
  -H "Content-Type: application/json" \
  --data @workflows/customer-onboarding.json

4. Find every failed execution in the last 24 hours

SINCE=$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)
curl "$BASE/executions?status=error&startedAfter=$SINCE&limit=250" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

5. Activate every workflow tagged prod after a maintenance window

IDS=$(curl -s "$BASE/workflows?tags=prod&active=false&limit=250" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" | jq -r '.data[].id')
for id in $IDS; do
  curl -X POST "$BASE/workflows/$id/activate" \
    -H "X-N8N-API-KEY: $N8N_API_KEY"
done

6. Create a credential without exposing the secret in CI logs

curl -X POST "$BASE/credentials" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"name\":\"Slack Prod\",\"type\":\"slackApi\",\"data\":{\"accessToken\":\"$SLACK_TOKEN\"}}"

Pagination, errors, and edge cases

Every list endpoint paginates with cursor-based navigation. The response shape is { "data": [...], "nextCursor": "abc123" | null }. When nextCursor is null, you have reached the end. Page size defaults to 100 and maxes at 250. The cursor is opaque — do not parse it; just pass it back unchanged on the next request.

Errors follow standard HTTP codes. 400 means your request body or query string is malformed. 401 means the API key is missing, malformed, or expired. 403 means the key is valid but lacks scope (Enterprise only) or you are trying to mutate a workflow owned by another user. 404 means the resource ID does not exist. 500 indicates a server-side bug — file a GitHub issue with the response body included.

Three edge cases bite production users. First, credential data is opaque — when you GET a workflow that uses a credential, the credential ID is included but its secret values are not, which means you cannot fully clone a workflow across instances via the API alone. You must POST the credential separately first. Second, activated workflows with cron triggers immediately schedule their next run when activated via the API — there is no "activate but don't run yet" flag. Third, execution data is purged according to your instance's retention settings (default 30 days on Cloud) and you cannot recover deleted executions via the API.

Webhooks vs API: when to use which

n8n's webhook trigger nodes give every workflow a public URL of the form https://your-instance/webhook/<path>. External services call that URL and the workflow runs. The REST API is for the inverse: your code calling n8n to manage the workflows themselves.

In production, you use both. Webhooks for the actual data flow (Stripe pings n8n, n8n syncs a customer to Salesforce). The REST API for the operational layer (CI deploys the workflow, observability pulls execution stats, an admin tool toggles workflows on/off during maintenance). The two are independent and authenticated differently — webhooks use the workflow's own signing secret if you configure one; the API uses the global account key.

SDKs and libraries

n8n does not ship an official SDK. The community maintains a few wrappers — n8n-api-client on npm is the most popular Node.js wrapper and there is a Python n8n-client on PyPI — but both are thin shims around the same REST surface. For most teams, raw fetch or requests is fine, because the API is genuinely small (about 25 endpoints total) and well-documented.

The official API reference includes an OpenAPI 3.0 spec at /api/v1/docs/swagger-ui on your instance. Point a code generator at it (openapi-typescript or openapi-generator) and you get a typed client in any language in two minutes.

Security checklist

Five things to do before the API touches a production workload. First, set a non-zero expiration on every key — 90 days is the right default. Second, use a dedicated key per integration (one for CI, one for observability, one for the admin tool) so revoking one does not break the others. Third, store keys in a secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault) and never commit them to source control. Fourth, log all API access at the reverse-proxy layer so you have an audit trail independent of n8n's own logs. Fifth, restrict outbound network access from your CI runners to only your n8n instance — if a CI runner is compromised, you do not want the leaked key to be reachable from arbitrary internet IPs.

FAQ

How do I authenticate with the n8n REST API?

Generate an API key in Settings → n8n API, then send it as the X-N8N-API-KEY header on every request. Enterprise users can additionally restrict keys with scopes. Non-enterprise keys grant full access to that user's resources.

Is the n8n API free to use?

Yes. The public REST API is included free in the n8n Community edition (self-hosted) and on every paid Cloud plan from Starter ($20/mo) upward. API keys are unlimited on Community and capped only by plan limits on Cloud.

What can I do with the n8n API?

Create, update, activate, deactivate and delete workflows; trigger executions; read execution data; manage users (admin); manage credentials; manage tags, variables and projects. All endpoints return JSON and follow REST conventions.

What is the rate limit on the n8n API?

Self-hosted Community has no enforced rate limit. Cloud plans enforce per-plan execution limits rather than raw request rate limits, but bursts above ~100 requests per second can be throttled. Use pagination (limit + cursor) for large reads.

How is the n8n API different from webhooks?

Webhooks are inbound triggers — external systems call your n8n workflow. The REST API is outbound management — your application calls n8n to administer workflows, fetch executions, or programmatically create flows. Most production deployments use both.

Can I deploy n8n workflows from CI/CD using the API?

Yes. Export workflow JSON from your source environment, then POST to /workflows in the target environment. Many teams version-control workflows as JSON and use GitHub Actions or GitLab CI to deploy via the API on merge to main.

Where to go next

If you are evaluating n8n itself rather than just the API, read our full n8n review for 2026 — pricing, feature depth, and where it wins versus Zapier. For the head-to-head: n8n vs Zapier and n8n vs Make. For the pricing-only deep-dive, see n8n Pricing 2026. For the bigger picture of agentic automation tools, our AI Workflow Automation by Industry pillar maps the landscape by sector.

Cited sources: n8n public REST API docs, n8n API authentication guide, n8n-docs source on GitHub, n8n API reference.