The n8n Credential Maze: OAuth, API Keys, and Token Refresh Explained

You have a workflow idea. Connect Slack to Google Sheets, pipe HubSpot contacts into your CRM, sync GitHub issues with Linear. The logic is simple. Five nodes, a couple of branches. You could build it in twenty minutes.

Then you hit the credential setup screen.

Google wants OAuth 2.0 with a consent screen, a redirect URI, specific scopes, and a client ID from a GCP project you need to create. Slack needs an app manifest, a bot token, and socket mode configuration. HubSpot offers both OAuth and API keys, with different permission models for each. And that twenty-minute workflow turns into a two-hour rabbit hole of documentation tabs, redirect URI mismatches, and "invalid_grant" errors.

Credential setup is the single biggest time sink in n8n workflow development. Not because n8n handles it poorly - it actually has solid credential management - but because every third-party app implements authentication differently, documentation is scattered, and small mistakes produce cryptic errors.

This guide covers the practical patterns for getting credentials working in n8n, the decision framework for choosing between auth methods, and the token refresh configuration that prevents your workflows from dying at 3 AM.

The Three Authentication Models

Every n8n integration uses one of three authentication approaches. Knowing which one you need before you start saves a surprising amount of time.

API Keys

The simplest model. The service gives you a static string, you paste it into n8n, and every request includes that key as a header or query parameter.

Common examples: SendGrid, Airtable, OpenAI, Notion (internal integrations), most webhook-based services.

How to set up in n8n:

1. Go to Settings > Credentials > Add Credential
2. Select the service (e.g., "Airtable API")
3. Paste your API key
4. Save and test

API keys are straightforward but come with tradeoffs. They don't expire automatically (good for reliability, bad for security). They grant broad access - you can't scope an API key to "read-only on this one table" the way you can with OAuth scopes. And if someone gets your key, they have your access until you rotate it.

Best practice: Create dedicated API keys for n8n rather than reusing keys from other integrations. If you need to revoke access, you only break the n8n connection, not everything else.

OAuth 2.0

The industry standard for delegated authorization. Instead of sharing a password or static key, you grant n8n specific permissions through an authorization flow. The service issues a short-lived access token and a longer-lived refresh token.

Common examples: Google (all services), Slack, HubSpot, Microsoft 365, Salesforce, GitHub.

The general setup pattern:

1. Create an "app" or "project" in the service's developer console
2. Configure a redirect URI (n8n provides this)
3. Select the scopes (permissions) your workflow needs
4. Get a Client ID and Client Secret
5. Enter those into n8n's credential form
6. Click "Connect" to go through the OAuth consent flow
7. n8n stores the resulting tokens

This is where most people get stuck. Each step has service-specific quirks, and one wrong value produces an error that points you in the wrong direction.

Bearer Tokens / Personal Access Tokens

A middle ground. You generate a token in the service's settings, and n8n sends it as a Bearer header. Similar to API keys but often scoped and sometimes with expiration dates.

Common examples: GitHub (Personal Access Tokens), GitLab, Jira, Linear, Notion (public integrations).

Setup in n8n: Usually the "Header Auth" credential type with Authorization as the header name and Bearer your-token-here as the value.

OAuth 2.0 Deep Dive: The Three Apps That Trip Everyone Up

Google (Gmail, Sheets, Drive, Calendar)

Google's OAuth setup is the most common pain point in n8n, and it follows the same pattern for every Google service.

Step 1: Create a GCP Project

Go to console.cloud.google.com, create a new project (or use an existing one). Name it something recognizable like "n8n Automations."

Step 2: Enable the API

In the GCP project, go to APIs & Services > Library. Search for the specific API (Gmail API, Google Sheets API, etc.) and enable it. This step is easy to forget - your OAuth credentials will work but every API call returns a 403.

Step 3: Configure the OAuth Consent Screen

APIs & Services > OAuth consent screen. Choose "External" unless you have Google Workspace (then choose "Internal" for simpler setup). Fill in the app name and your email. Add the scopes your workflow needs.

For Google Sheets: https://www.googleapis.com/auth/spreadsheets For Gmail send: https://www.googleapis.com/auth/gmail.send For Drive read: https://www.googleapis.com/auth/drive.readonly

The testing trap: If you set the consent screen to External and don't publish the app, Google puts it in "Testing" mode. Only emails you explicitly add as test users can authorize. And tokens expire after 7 days. This causes the classic "it worked for a week then stopped" problem.

Fix: Either publish the app (it doesn't need verification for personal use with fewer than 100 users) or switch to Internal if you're on Workspace.

Step 4: Create OAuth Credentials

APIs & Services > Credentials > Create Credentials > OAuth client ID. Choose "Web application." Add the redirect URI that n8n shows you in the credential setup form.

The redirect URI format for self-hosted n8n is: https://your-n8n-domain.com/rest/oauth2-credential/callback

For n8n Cloud: https://app.n8n.cloud/rest/oauth2-credential/callback

The most common error here: Using http instead of https in the redirect URI, or including a trailing slash when the GCP console doesn't expect one. The URI must match exactly.

Step 5: Connect in n8n

Paste the Client ID and Client Secret into n8n's Google credential form. Click "Sign in with Google." Authorize the requested scopes. Done.

Slack

Slack's auth model changed significantly when they moved to "granular bot permissions." Old tutorials showing "Legacy tokens" or "Classic apps" will waste your time.

The correct flow:

1. Go to api.slack.com/apps and create a new app "From scratch"
2. Under OAuth & Permissions, add bot token scopes. Common ones: chat:write, channels:read, users:read, files:write
3. Add the redirect URL from n8n's Slack OAuth2 credential form
4. Install the app to your workspace
5. Copy the Client ID and Client Secret from Basic Information
6. Connect through n8n

Common issue: Adding user token scopes instead of bot token scopes. In n8n, you almost always want bot scopes. User scopes act on behalf of a specific user, which breaks when that person leaves the company.

HubSpot

HubSpot gives you a choice: OAuth 2.0 or a private app API key. The decision matters.

Use OAuth 2.0 if: You're building for multiple HubSpot portals, need granular scopes, or want token refresh.

Use a Private App if: You're connecting to a single HubSpot account you control. This is simpler - create a private app in HubSpot settings, select scopes, get an access token. Paste it into n8n as "HubSpot API" credential type.

Most single-company automations should use the private app approach. It takes two minutes instead of fifteen.

The API Key vs OAuth Decision Matrix

When a service offers both options, here's the decision framework:

Factor	Choose API Key	Choose OAuth 2.0
Setup time	Need it working now	Can spend 15 min on setup
Token expiry	Want set-and-forget	OK with refresh handling
Permission scope	Broad access is fine	Need granular permissions
Multi-user	Single account	Multiple users/accounts
Security priority	Internal/low-risk	External-facing/sensitive
Rotation policy	Manual rotation OK	Want automatic refresh

The general rule: if the workflow touches customer data or runs in a team environment, use OAuth. If it's a personal automation connecting your own tools, API keys are fine.

Token Refresh: Why Workflows Break at 3 AM

OAuth access tokens expire. Usually after one hour. When they expire, n8n uses the refresh token to get a new access token. This happens automatically - most of the time.

Here's when it fails:

Refresh token rotation: Some services (Google in testing mode, some Microsoft configs) issue a new refresh token with every access token refresh. If n8n doesn't store the new refresh token correctly (rare but possible after updates), the next refresh attempt uses an old, invalidated token. The workflow breaks silently.

Refresh token expiry: Microsoft 365 refresh tokens expire after 90 days of inactivity. If a workflow runs weekly and you skip two months, the refresh token dies. You need to re-authorize.

Consent revocation: Someone revokes n8n's access from the service's "Connected Apps" settings. Common in shared workspaces where admins do security audits.

Scope changes: You update the credential to request additional scopes but don't re-authorize. The existing token doesn't have the new permissions.

How to monitor for token failures

Set up a dedicated error-handling workflow:

1. Create a workflow with an Error Trigger node
2. Filter for credential-related errors (look for "401," "invalid_grant," "token expired" in the error message)
3. Send a notification to Slack, email, or wherever you'll see it
4. Include the workflow name and credential name in the notification

This is unglamorous work, but it's the difference between "I fixed it in five minutes" and "this has been broken for two weeks."

Common Credential Errors and Fixes

"redirect_uri_mismatch" (Google, most OAuth providers)

The redirect URI in n8n doesn't match the one registered in the app. Check for: http vs https, trailing slashes, port numbers, different domains. Copy the exact URI from n8n's credential form into the provider's app settings.

"invalid_client" (Google, Slack)

The Client ID or Client Secret is wrong. Common cause: copying from the wrong app or project. GCP projects can have multiple OAuth clients - make sure you're using credentials from the right one.

"invalid_grant" (Google, Microsoft)

The refresh token is invalid. Causes: token was revoked, app is in testing mode and token expired after 7 days, or the user changed their password. Fix: disconnect and reconnect the credential in n8n.

"insufficient_scope" (Google, GitHub)

The token doesn't have permission for the requested action. You authorized with gmail.readonly but the workflow tries to send an email (needs gmail.send). Update the scopes in the app settings AND re-authorize - just changing scopes doesn't update existing tokens.

"AADSTS" errors (Microsoft 365)

Any error starting with AADSTS is from Azure AD. The error codes are well-documented: search "AADSTS[error-code]" and Microsoft's docs will tell you the exact issue. The most common one, AADSTS700016, means the app isn't registered in the correct tenant.

Security Best Practices

Never hardcode credentials in workflow expressions. Use n8n's credential system for every secret. If you need a value that isn't covered by a built-in credential type, use the "Header Auth" or "Custom API" credential types.

Isolate credentials per workflow. Create separate API keys or OAuth apps for separate workflows. When one workflow is decommissioned, revoke its credentials without affecting others.

Use the minimum scopes needed. Don't request drive (full access) when you only need drive.readonly. Scoping limits the blast radius if credentials are compromised.

Audit connected apps quarterly. Check your Google, Slack, and Microsoft "Connected Apps" settings. Revoke access for workflows you no longer run.

Self-hosted n8n: protect the credentials endpoint. n8n encrypts credentials at rest, but the encryption key must be set via the N8N_ENCRYPTION_KEY environment variable. If you haven't set this, n8n generates one automatically - but it changes if you redeploy, which makes all stored credentials unreadable.

Set it once, store it securely, and never change it:

export N8N_ENCRYPTION_KEY="your-random-32-character-string"

The Kiln Approach to Credentials

One of the hidden benefits of generating workflows through Kiln is the credential checklist. When Kiln's agents build a workflow, the Technical Writer agent produces a setup guide that includes:

• Which authentication method each connected app needs (OAuth, API key, or bearer token)
• The exact scopes to request for the workflow's specific actions
• Direct links to the developer console or API key page for each service
• Step-by-step instructions for the redirect URI configuration

This doesn't eliminate the setup work - you still need to create the apps and authorize the connections - but it removes the research phase. Instead of reading four different documentation pages to figure out which Google scope covers "append a row to a sheet," you get the answer in the workflow's setup guide.

Credential Setup Checklist

Before you start connecting any service, run through this list:

1. Identify the auth method. Check n8n's credential options for the service. If it shows "OAuth2," you need to create an app.
2. Create a dedicated app/project. Don't reuse apps across unrelated workflows.
3. Copy the redirect URI from n8n first. Have it ready before you start configuring the provider.
4. Request minimum scopes. Start with the least permissions needed. Add more later if required.
5. Test immediately after connecting. Run a simple read operation before building the full workflow.
6. Set up error monitoring. An Error Trigger workflow that alerts you on 401/403 errors.
7. Document what you set up. Which GCP project, which Slack app, which scopes. You'll need this when something breaks six months from now.

Wrapping Up

Credential setup isn't glamorous. There's no shortcut that makes OAuth 2.0 simpler or API key management more exciting. But getting credentials right from the start - correct scopes, proper redirect URIs, refresh token monitoring - prevents the class of failures that are hardest to debug: the ones where your workflow worked perfectly for weeks and then stopped with no code changes.

The patterns in this guide apply regardless of how you build your workflows. Whether you're clicking through n8n's UI, importing JSON, or generating workflows with Kiln, the credential layer is something you configure once and maintain forever. Invest the time to get it right, and your workflows stay reliable.