Managing credentials: keys, OAuth, and where sharing stops

Why credentials deserve real care

When you dropped a Slack node onto the canvas in Chapter 11, n8n made you pick a "Credential to connect with". What sits in that dropdown is a credential — one SaaS account authorization that n8n keeps for you. Without it, the Slack node still throws Authentication failed at run time even when every node parameter is filled in correctly.

But credentials come with a dilemma:

• Manage them nowhere central: every workflow stores its own copy of the token, so one password change means editing a dozen of them; and when a colleague leaves, you have no idea where they tucked their tokens away.
• Share one copy across the company: the moment somebody slips and exports a workflow as JSON to share it, the token leaks.
• Fail to back up the encryption key: after a server move or a disaster restore, the credential data is still there but nothing can open it — every workflow dies.

This chapter settles three things: (1) how to create both credential types (OAuth2 vs API Key); (2) the three ways to share with colleagues, and where each one stops; (3) where credentials actually live, how the encryption works, and what you have to carry along when you back up.

What a credential actually is

In one sentence: a credential is the set of account authorization details n8n keeps for you, so a node can pull them out automatically when it calls an outside service. Think of your browser's saved passwords, but for workflows.

Three properties matter:

• It lives in the n8n database, not on your computer and not in the workflow JSON file. Move a workflow to another n8n and you have to bind the credential again.
• It is stored encrypted, using the n8n instance's N8N_ENCRYPTION_KEY environment variable. Not even you can see the plaintext (only the credential's name and type).
• It is user-level (owned by whoever created it), not workflow-level. A credential you create goes into your personal space by default, and other signed-in users cannot see it; the same account can reuse one credential across many workflows and many nodes. Delete a credential and every node that references it turns red and stops working. To share it across people you go through the "Sharing" mechanism (see the Sharing with colleagues section).

Where is the Credentials page? Chapter 3 already walked you past it — Credentials at the bottom of the sidebar (in some versions the icon is a little key). Click in and you get a table listing every credential in your workspace: name, type and last-modified time.

The two credential types

The hundreds of credential types fall into two groups. Recognize these two and you can handle almost anything:

Two rarer variants exist as well — do not be alarmed when you meet them:

• Basic Auth: paste a username and password directly (common on older internal APIs, some corporate LDAP setups for example).
• Header Auth / Custom Auth: some non-standard APIs want a special field in the header, and this flexible authorization type covers them. It is the usual partner for the HTTP Request node when you call an API in the wild.

Hands-on: create a Google OAuth2 credential

The most common situation — the company needs a workflow to read and write Google Sheet, send Gmail and store files on Drive, all authorized by the same Google OAuth2 credential. Walk through it once and you will have it:

1. Sidebar Credentials → New credential

   Click Credentials in the sidebar, then Add credential at the top right (or Create new credential in the middle of an empty workspace). A "Select credential type" search box opens.

2. Search for Google → pick the right credential type

   Type google and a pile of options appears: Google OAuth2 API (the generic one), Google Sheets OAuth2 API, Gmail OAuth2 API, Google Drive OAuth2 API and so on. The rule is pick the OAuth2 credential that matches the node you are going to use — it is all Google OAuth underneath, but the scopes differ. For the Gmail node, pick Gmail OAuth2 API.

3. Create an OAuth Client in the Google Cloud Console (for the Client ID/Secret)

   If this is your first one, n8n asks you for a Client ID and a Client Secret — you get both by creating an OAuth 2.0 Client ID at console.cloud.google.com. The steps: create a Project → APIs & Services → Credentials → Create Credentials → OAuth client ID → Web application → paste the OAuth Redirect URL n8n shows you (something like https://n8n.woowtech.io/rest/oauth2-credential/callback) into Authorized redirect URIs → save, and you have the Client ID / Secret.

   Tip: WoowTech IT has already built a shared OAuth Client, so just ask IT for the Client ID / Secret instead of opening a new Project yourself. Sharing one keeps quota management and audit logs in a single place.

4. Paste the Client ID / Secret into n8n

   Back in the n8n credential form, paste the Client ID you just got from the Google Console into the Client ID field and the Client Secret into the Client Secret field. Leave Scope at its default in most cases (each credential type ships with the scopes people usually need — Gmail OAuth includes send/read/labels, Sheets OAuth includes read and write).

5. Press Sign in with Google → Allow → get the token

   Press Sign in with Google at the top right (other versions call it Connect my account or OAuth2) and a new window opens on the Google consent screen — pick your Google account → read the "n8n wants to access your Gmail…" list → press Allow. Once the popup closes, the n8n page shows a green check and Account connected.

6. Name it and save

   Change the credential name at the top to something recognizable, for example Gmail ([email protected]) or Google Sheets - CS team. Press Save. From now on that name is selectable in the Credential dropdown of your Gmail / Sheet / Drive nodes.

Hands-on: create an API key credential (OpenAI as the example)

The API Key type is far simpler than OAuth — no bouncing between sites, just one key pasted in. Using OpenAI as the example:

1. Create an API key in the OpenAI console

   Sign in at platform.openai.com/api-keys, press Create new secret key, give it a name (n8n-woow-prod, for example) and choose All permissions (or read-only if that is all you need). The key is shown exactly once — if you do not copy it you can never get it back, so paste it into n8n immediately.

2. Credentials page → New credential → search for OpenAI

   Back in n8n: sidebar Credentials → Add credential → type openai in the search box and pick OpenAI.

3. Paste the API key in

   There is a single API Key field; paste the key you just copied. Organization ID can usually stay empty (unless you belong to several OpenAI organizations and have to name one).

4. Name it and save

   Change the credential name to something like OpenAI (marketing team). Press Save — done, and much faster than OAuth.

How credentials relate to workflows

This is where a lot of beginners get lost — a credential and a workflow are two separate resources. Once that clicks, you understand why credentials do not travel with a workflow you move to another server.

Another way to look at it — the n8n database is really two big tables: one holds credentials (an encrypted safe full of tokens), one holds workflows (the node structure). A node inside a workflow stores only the reference "which credential ID I use"; the actual token value is not in the workflow file.

Three ways to share a credential with colleagues

Not everyone at a company wires up workflows with their own Google account — usually a team shares one [email protected], or uses a role account such as a Slack Bot. n8n's sharing model is the opposite of what you would expect — the default is "whoever created it owns it", not "shared across the company":

What to do in practice:

• Small Community teams: if you genuinely must share the marketing account's credential, the usual answer is that everyone signs in as the same n8n user (not ideal, but common), or each person rebuilds their own copy. If you need sharing you can rely on, upgrade to Enterprise.
• Enterprise / Cloud Pro and above: use the Sharing tab to allowlist specific colleagues, or create the company-account credential under a Project so members share it.
• Always name them clearly: put "who owns it / which team / what it is for" in the credential name, for example Slack Bot - #ops-alerts or OpenAI (billing: CS team), and avoid unreadable names like gmail1 and gmail2.

Where credentials are stored and how safe they are

Three questions IT always asks: where it lives, how the encryption works, what a backup has to include. All of them, in one go:

1. It lives in the n8n database (the credentials table)

   Whether you self-host on SQLite or on Postgres, credentials go into a table called credentials (or credentials_entity). One row per credential, with columns including id, name, type and data — and that data is the encrypted JSON blob (it holds the sensitive values: token, API key, OAuth refresh_token and the rest).

2. Encryption uses the N8N_ENCRYPTION_KEY environment variable

   On startup n8n reads the N8N_ENCRYPTION_KEY environment variable and uses it as the symmetric encryption key (AES from crypto-js underneath). Credentials are encrypted with that key before they go into the DB and decrypted on the way out. If the variable is not set the first time n8n starts, n8n generates one and writes it into the settings file under ~/.n8n (in practice ~/.n8n/config) — and from then on you must never lose that key. In a queue mode deployment, always set the N8N_ENCRYPTION_KEY environment variable by hand, and give every worker the same value, or the workers cannot decrypt the credentials.

3. Always carry the encryption key along with the backup

   Backing up n8n by dumping SQL alone is useless — every credential in the database is ciphertext, and if the new server has a different encryption key on restore, all of them become garbage nobody can open and every workflow dies. Do it properly: keep the DB dump, ~/.n8n/config and the value of the N8N_ENCRYPTION_KEY environment variable together, all three.

4. Not even the Owner sees the plaintext

   Even as the workspace Owner, the credential detail page shows the token field as blank (meaning "saved") or as a row of dots; you never see the real value. That is deliberate — it stops insiders, admins included, from copying tokens out by accident or on purpose. The only way to the plaintext is reading the DB with SQL and decrypting it with the encryption key (which needs root).

The day-to-day life of a credential

Every credential goes through these stages from creation to deletion. Learn them and you can run dozens of credentials without breaking a sweat:

Troubleshooting

The pitfalls you will hit sooner or later when you manage credentials, listed in one place:

1. The OAuth popup comes back and you are still not signed in

   Symptom: you press Sign in with Google, the popup opens the Google consent screen, you click Allow, and back in n8n it is still gray with no green check. Nine times out of ten the OAuth Redirect URI is wrong — the Authorized redirect URIs in the Google Console must match the URL shown on the n8n credential page exactly (https included, trailing slash included, domain included). Ask IT to compare the two sides and copy it across again.

2. A credential suddenly expires and stops working

   For OAuth types n8n refreshes the token automatically most of the time and you never notice. But these situations make the refresh fail and need a manual Reconnect: (1) the account's password was changed; (2) the app authorization was revoked by hand on the Google side; (3) the refresh token expired (Google expires one after 6 months of disuse); (4) the OAuth Client Secret was revoked in the Google Console.

3. A node turns red with Credential ID not found

   Two possibilities: (1) somebody deleted that credential — create a new one and re-pick it in the node's credential dropdown; (2) you exported the workflow JSON from n8n A into n8n B and the credential IDs do not line up — again, rebuild the credential in n8n B and bind it again. That is the unavoidable price of keeping credentials and workflows apart.

4. The Test button returns 401 / 403

   Two possibilities: (1) an API Key type — the key is mistyped, you dropped a character while copying, or the key has already been revoked in the console; (2) an OAuth type — the scope is not enough (you picked Google Sheets OAuth2, say, but the same OAuth authorization never granted Drive access), so Reconnect once more and tick every permission you need on the Google page.

5. The Test button passes but the node still will not run

   Test usually only makes "the simplest possible API call" to prove the account is alive (GET /me, for example) — but your node needs a more advanced operation (posting to a private Slack channel, writing to a locked Google Sheet), and the scope or permissions may fall short. Test passes, and the real run throws insufficient_permissions; Reconnect and make sure the scopes are complete.

6. After a backup restore, no credential opens

   The classic symptom: you restore the DB dump on a new server and every credential shows an error or simply cannot be decrypted. The cause: N8N_ENCRYPTION_KEY did not come along. The fix: find the old server's encryption key (in ~/.n8n/config or in the environment variables), set the same-named environment variable on the new server, and restart n8n. This is the most common restore disaster; put the key into your backup plan from day one.

7. The credential I just created is missing from the dropdown

   Two reasons: (1) the credential type does not match the node — you will never find a Gmail credential inside a Slack node, because the Slack node only accepts Slack API or Slack OAuth2; (2) the workspace you created the credential in is not the workspace you are editing the workflow in (only Enterprise has the project concept; on Community there is usually one workspace with one copy).

FAQ