n8n Gmail OAuth Setup for Self-Hosted n8n

On n8n Cloud, connecting Gmail takes one click: you sign in with Google and n8n handles the OAuth app. On a self-hosted instance, you supply your own Google OAuth client. It takes a few steps in Google Cloud, and most problems come down to one of three things: the redirect URL, the consent screen's test users, or the app's publishing status.

This guide covers the setup end to end and lists fixes for the errors people hit most.

Before you start

• A reachable n8n URL. Google needs to redirect your browser back to n8n after sign-in. For a server, that means a public HTTPS address (for example https://n8n.example.com) behind a reverse proxy. For local testing, http://localhost:5678 is accepted by Google as a redirect.
• Correct base URL settings. n8n builds its OAuth callback URL from its configured address. If you run behind a proxy, set N8N_EDITOR_BASE_URL (and usually WEBHOOK_URL) to your public URL, along with N8N_PROTOCOL=https and N8N_HOST. Otherwise n8n may show a callback with the wrong host or http, and Google will reject it.
• A Google account that can create projects in Google Cloud Console.

Step 1: Create a Google Cloud project

1. Go to console.cloud.google.com.
2. Open the project picker and choose New Project. Give it a clear name, such as "n8n Gmail".
3. Select the new project.

Step 2: Enable the Gmail API

1. Go to APIs & Services > Library.
2. Search for Gmail API and click Enable.

Without this, sign-in may succeed but every Gmail node call will fail.

Step 3: Configure the consent screen

Google has reorganized this area over time; recent consoles group it under Google Auth Platform (Branding, Audience, Data Access, Clients), while older ones call it OAuth consent screen. The settings are the same.

1. App information: an app name and a support email. Something like "My n8n" is fine for personal use.
2. Audience / User type: - Internal if you use Google Workspace and only accounts in your organization will connect. This avoids test-user limits. - External for personal Gmail accounts or mixed use.
3. Test users (External only): while the app is in Testing, only listed accounts can sign in. Add every Gmail address you plan to connect.
4. Scopes / Data Access: you can leave this alone. n8n requests the scopes it needs during sign-in.

A note on Testing vs. Production

For External apps in Testing status, Google's refresh tokens expire after 7 days. In n8n, this shows up as the Gmail credential suddenly failing a week after setup. You have two choices:

• Reconnect weekly in n8n (fine for experiments).
• Publish the app (Audience > Publish app). Gmail scopes are classified as restricted, so an unverified production app shows a "Google hasn't verified this app" warning during sign-in. For connecting your own accounts, you can continue through Advanced and proceed. Full verification is only needed if you plan to let many outside users connect.

Workspace users on an Internal app don't face the 7-day expiry.

Step 4: Create the OAuth client

1. Go to Clients (or APIs & Services > Credentials) and choose Create client / Create Credentials > OAuth client ID.
2. Application type: Web application.
3. Name: anything, such as "n8n".
4. Authorized redirect URIs: paste the OAuth Redirect URL from n8n (next step shows where to find it). It looks like:

https://n8n.example.com/rest/oauth2-credential/callback

5. Click Create and copy the Client ID and Client secret.

Step 5: Create the Gmail credential in n8n

1. In n8n, go to Credentials > Add credential and choose Gmail OAuth2 API.
2. Copy the OAuth Redirect URL shown in the credential form. Make sure it exactly matches what you added in Google Cloud: same protocol, host, port and path.
3. Paste the Client ID and Client secret.
4. Click Sign in with Google, choose your account and approve the requested access.
5. Save the credential.

Test it by adding a Gmail node (Message > Get Many, limit 1) and running it.

Common errors and fixes

Error 400: redirect_uri_mismatch The URL n8n sent doesn't exactly match an authorized redirect URI. Compare them character by character. Common causes: http vs https, a missing or extra port, a trailing slash, or n8n showing an internal hostname because N8N_EDITOR_BASE_URL isn't set. Google may take a few minutes to apply changes to redirect URIs.

Error 403: access_denied or "app is in testing" The account isn't on the test user list. Add it under Audience / Test users and try again.

Works for a week, then fails (invalid_grant) The app is External and in Testing, so the refresh token expired. Reconnect, or publish the app as described above.

Sign-in works, but Gmail nodes fail with an API error The Gmail API isn't enabled in the same project as your OAuth client. Enable it in Step 2 and retry.

Popup closes and nothing happens Check that your browser allows popups for your n8n domain, and that your reverse proxy passes the /rest/oauth2-credential/callback path through to n8n.

Security tips

• Keep the client secret in n8n credentials only. Don't paste it into workflow nodes or share exported workflows that contain it.
• Connect only the accounts you need, and remove access you no longer use from your Google Account's security settings under third-party connections.
• Restrict who can log in to your n8n instance, since anyone with editor access can use the connected credential.

What to build next

With Gmail connected, you can automate sorting, labeling and drafting. Our templates use this exact credential type and run on self-hosted n8n as well as n8n Cloud, with your own OpenAI key:

• Inbox Triage Lite (free): four labels to tidy new mail.
• AI Inbox Triage ($29): six categories plus reply drafts for urgent, sales and support emails.
• AI Lead Pursuit ($29): follow-up drafts for quiet sales leads, which wait for you to send.

Paid templates include a 14-day refund window.

n8n is a trademark of n8n GmbH. ReadyUpAgents is independent and not affiliated with or endorsed by n8n.