n8n Credentials Explained: Connect Apps Securely

Before n8n can act on your behalf in another app, it needs permission. That permission lives in a credential — a securely stored bundle of authentication details that n8n uses to talk to services like Gmail, Slack, Airtable, or any HTTP API. Get credentials right and your automations connect cleanly and stay secure. Get them wrong and you face cryptic 401s, leaked secrets, or, on self-hosted setups, the nightmare of losing every connection at once.

This guide explains exactly how credentials work, the different types, how they are encrypted, how to set up both API-key and OAuth2 connections step by step, and the security practices that keep your secrets out of the wrong hands. If you are still getting oriented, start with what n8n is and the beginner's guide.

What are credentials in n8n?#

A credential stores the authentication details that let n8n prove to an external service that it is allowed to act. Depending on the app that means an API key, an OAuth2 access token, a username and password, or a custom header. You create a credential once, and any node that supports that app can select it from a dropdown.

The key design decision in n8n is that credentials are stored separately from workflows. A workflow references a credential by ID; it never embeds the secret itself. This matters for several reasons:

• You can update a rotated key in one place and every workflow that uses it keeps working — no editing dozens of nodes.
• You can export, share, or version-control a workflow without leaking secrets, because the secret is not inside the workflow JSON.
• Different team members can use the same connection without each knowing the underlying key.

Credential types and when to use each#

n8n supports several authentication styles. Most managed integrations pick the right one automatically, but it helps to know what each is for — especially when you reach for the generic HTTP Request node against an API that has no dedicated integration.

As a rule of thumb: prefer OAuth2 when the app offers it, fall back to an API key when it does not, and reach for header or basic auth only when an API forces your hand.

How credentials are stored and encrypted#

n8n never stores credential secrets in plain text. When you save a credential, n8n encrypts the sensitive fields and writes the ciphertext to its database. Everything hinges on one secret: the encryption key.

On self-hosted instances this is the N8N_ENCRYPTION_KEY environment variable. If you do not set one, n8n generates a random key on first run and saves it to a config file inside the n8n data directory (~/.n8n/config by default). Either way, that key is the only thing that can decrypt your credentials. Lose it and every stored credential becomes unreadable — there is no master reset, no recovery flow, no support ticket that brings them back.

Set the key explicitly so it survives container restarts and is part of your backups. In Docker, pass it as an environment variable:

# docker run
docker run -d \
  --name n8n \
  -p 5678:5678 \
  -e N8N_ENCRYPTION_KEY="a-long-random-string-keep-this-secret" \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Or in a docker-compose.yml / .env file:

# .env
N8N_ENCRYPTION_KEY=a-long-random-string-keep-this-secret

Generate a strong value with something like openssl rand -hex 32. Treat it like a database password: store it in a secrets manager, never commit it to Git, and use the same value across every replica of the same instance so they can all decrypt the shared database.

On n8n Cloud, encryption-key management is handled for you, which is one of the main reasons teams choose Cloud over self-hosting. If you do self-host, popular routes are a VPS provider like Hostinger or DigitalOcean — just remember the encryption-key responsibility comes with the control.

Setting up an API-key credential#

API-key connections are the simplest. Here is the full flow, using an app like Airtable as the example:

1. In the external app, generate an API key or personal access token. Scope it to only the data the workflow needs — for Airtable that means selecting specific bases and permissions rather than full account access.
2. In n8n, add the app's node to a workflow (or open an existing one).
3. Open the Credential to connect with dropdown and choose Create new credential.
4. Paste the API key into the field. Some apps also need a base URL, account ID, or region.
5. Click Save. n8n encrypts the value and runs a connection test where the integration supports it.
6. The credential now appears in the dropdown for every node of that type across all your workflows.

If the test fails immediately, the key is almost always wrong, has trailing whitespace, or lacks the required scope — see the troubleshooting table below.

Setting up an OAuth2 credential (Google / Gmail)#

OAuth2 is more involved because it requires a redirect handshake, but it produces short-lived tokens that refresh automatically and can be revoked from the provider's side. On n8n Cloud, connecting Gmail or Google Sheets is often as simple as clicking "Connect" and signing in, because n8n provides the OAuth client. On self-hosted, you must supply your own Google Cloud OAuth client. Here is the self-hosted flow:

1. In n8n, create a new Gmail (or Google) OAuth2 credential. n8n shows you an OAuth Redirect URL — copy it. It looks like https://your-n8n-domain/rest/oauth2-credential/callback.
2. Go to the Google Cloud Console and create or select a project.
3. Enable the API you need (for Gmail, the Gmail API) under APIs and Services.
4. Configure the OAuth consent screen: set the app name, support email, and add the specific scopes you need. Add yourself as a test user while the app is unverified.
5. Create an OAuth 2.0 Client ID of type Web application. Under authorized redirect URIs, paste the redirect URL from step 1 exactly.
6. Copy the generated Client ID and Client Secret back into the n8n credential fields.
7. Click Sign in with Google (or Connect) in n8n, complete the Google login, and approve the requested scopes.
8. Save. n8n stores the resulting refresh token, encrypted, and uses it to mint fresh access tokens automatically.

The single most common failure here is a redirect URI mismatch: the URL in Google Cloud must match what n8n generated character for character, including https, the domain, and the path. A correct public domain (not localhost for production) and HTTPS are required.

Sharing and reusing credentials across workflows#

Because credentials live independently, reuse is automatic. Once a credential exists, it shows up in the dropdown of every compatible node in every workflow you own. Change the key once and all references update — no need to touch individual nodes.

On team plans and Enterprise, n8n adds credential sharing: you can grant specific users or projects access to a credential without revealing the underlying secret. A teammate can build a workflow that sends Slack messages using a shared credential while never seeing the token itself. This keeps secret knowledge contained while letting the whole team build.

A practical pattern is to name credentials clearly by purpose and environment — for example Gmail – Marketing (prod) versus Gmail – Sandbox (dev) — so nobody accidentally points a test workflow at production data.

Credentials in the HTTP Request node#

When you call an API that has no dedicated n8n node, the HTTP Request node handles it. It offers two authentication paths:

• Predefined credential type — choose from n8n's library of known services (for example, "Google Sheets API"). n8n knows the auth scheme and injects the right headers for you. Use this whenever the service you are calling is in the list, even if there is no full node, because it saves you from hand-building headers.
• Generic credentials — for everything else. You pick Basic Auth, Header Auth, Query Auth, or OAuth2 and configure it manually. For a typical API-key service you would create a Header Auth credential like this:

Name:  Authorization
Value: Bearer YOUR_API_KEY

Define that once as a generic Header Auth credential and reuse it across every HTTP Request node hitting that API. Crucially, never type the raw secret into a header field directly in the node — always store it as a credential so it gets encrypted and stays out of exported workflow JSON.

Security best practices#

• Least privilege. Grant a credential only the scopes and resources the workflow actually uses. A reporting workflow needs read access, not full read-write-admin.
• Use OAuth2 where available. Short-lived, refreshable, revocable tokens beat long-lived static keys.
• Separate keys per environment. Use distinct credentials and keys for dev, staging, and production so a leaked test key cannot touch live data.
• Rotate regularly and revoke the unused. Schedule key rotation and delete credentials for apps you no longer integrate with.
• Never hardcode secrets. Keep keys out of node fields, workflow notes, expressions, and Git. Always use the credential store.
• Protect the encryption key. On self-hosted, back up N8N_ENCRYPTION_KEY securely and restrict who can read it.
• Mind your logs. Avoid printing full responses that may echo tokens, and lock down access to execution logs.

Troubleshooting auth errors#

Most credential problems surface as HTTP status codes. Knowing the difference points you straight at the fix.

The mental shortcut: 401 is about who you are, 403 is about what you are allowed to do. If a credential that worked yesterday suddenly throws 401, suspect a rotated key or an OAuth token that could not refresh. If you get 403, the connection is valid but you need more scope.

Self-hosting considerations#

Self-hosting gives you full control and full responsibility. Beyond setting and backing up N8N_ENCRYPTION_KEY, keep these in mind:

• Use the same key across replicas. Every n8n instance sharing one database must use the identical encryption key, or they cannot decrypt each other's credentials.
• Run behind HTTPS. OAuth providers require secure redirect URLs, and Basic/Header auth should never travel over plain HTTP.
• Back up the database and key together but stored separately. A database backup is useless for credentials without the matching key, and vice versa.
• Plan for OAuth clients. Each provider (Google, Microsoft, Slack) needs its own OAuth app and redirect URL configured against your public domain.

If managing keys and OAuth clients sounds like more than you want to own, n8n Cloud removes that burden. Weigh the trade-offs in our Cloud vs self-hosted comparison.

Keep learning#

With credentials connected, you are ready to move data around with expressions, trigger automations via webhooks, and build your first end-to-end flow using the beginner's guide. Credentials are the quiet foundation under all of it — set them up carefully once, protect the keys, and the rest of your automations just work.