Setting up OAuth2 for Google in n8n: Gmail, Sheets, Drive and Calendar step by step

Connecting Gmail, Google Sheets, Drive or Calendar to n8n is often the very first thing you want to do — and the very first thing that gets stuck. Unlike a simple API key you copy and paste, Google requires the OAuth2 protocol: a project in Google Cloud Console, APIs to enable, a consent screen to configure, a client credential to create, and a redirect URI that has to match character for character. Nothing insurmountable, but the sequence of steps trips up most beginners, and a single wrong checkbox is enough to produce an opaque error message. This guide walks the full path, from the Google Cloud project to the "Sign in with Google" button in n8n, then reviews the pitfalls that waste hours.

Let's say it up front: this complexity is not just a beginner's impression. The formal analysis of the protocol by Fett, Küsters and Schmitz, published at the ACM CCS conference in 2016 (A Comprehensive Formal Security Analysis of OAuth 2.0, see on Google Scholar), uncovered several vulnerabilities in real-world OAuth configurations and implementations, notably around redirect URIs. In other words: the strictness Google enforces on every URI and every scope isn't administrative zeal — it's precisely what prevents a third party from hijacking your access tokens. Ten minutes spent configuring things properly is not wasted time.

Overview: what we're building

The principle of OAuth2 fits in one sentence: instead of handing your Google password to n8n, you register n8n as an "application" with Google, and Google issues that application access tokens limited to the permissions (scopes) you explicitly granted. Concretely, you need:

1. A project in Google Cloud Console.
2. The APIs enabled for each target service (Gmail API, Google Sheets API, Google Drive API, Google Calendar API).
3. An OAuth consent screen configured.
4. An OAuth 2.0 credential of the web application type, which gives you a client ID and a client secret.
5. An n8n credential in which to paste those two values, before authenticating via "Sign in with Google".

Good news: steps 1 to 4 only need to be done once. The same project and the same client ID / client secret pair then serve every Google credential in your n8n instance.

Step 1: create a project in Google Cloud Console

Head to console.cloud.google.com, sign in with the Google account you plan to use in your workflows, and create a new project. The name has no technical significance — "n8n-automations" will do fine. No credit card is required: the Google Workspace APIs used here are free within quota limits that are more than enough for typical automation use.

Step 2: enable the required APIs

In the project's API library (the "APIs & Services" section), search for and enable each API matching the services you want to drive from n8n:

• Gmail API to read and send emails — the prerequisite of any AI email automation workflow;
• Google Sheets API to manipulate spreadsheets (see our Google Sheets guide);
• Google Drive API for files and folders (our Google Drive guide covers the use cases);
• Google Calendar API for calendar events (Google Calendar guide).

Enable them all right away if you know you'll need them: it's free, and it saves you a round trip later. An API that hasn't been enabled produces a misleading authorization error on the n8n side, when the actual problem is simply that the project isn't allowed to call that service.

Step 3: configure the OAuth consent screen

The consent screen is the page Google will display at "Sign in with Google" time to ask you to grant the permissions. Configuring it involves a few choices:

• User type: if your account belongs to a Google Workspace organization, choose "Internal" — the app will be limited to your organization's accounts, with no verification process. With a personal Gmail account, only the "External" type is available.
• Basic information: application name (what you'll see on the consent screen), support email, developer contact email. Again, the exact values barely matter for personal use.
• Testing vs production mode: an external app starts in testing mode. In that mode, only the test users explicitly added in the configuration can authenticate — make absolutely sure to add the Google address you'll use in n8n, or the connection will be refused right away.

Testing mode hides a major trap we'll detail below: refresh tokens there expire after 7 days. For an n8n instance that has to run continuously, plan to push the app to production (a simple button on the consent screen) once your first tests succeed. For personal use with your own scopes, this switch doesn't trigger any blocking requirement — you'll simply see the "unverified app" warning, which can be bypassed.

Step 4: create the OAuth 2.0 credential

On to the project's "Credentials" section: create a credential of the OAuth client ID type, choosing Web application as the application type. This is where the most critical step of the whole process happens: the Authorized redirect URIs field.

Open n8n in another tab and create the target credential (for example Gmail OAuth2 API for the Gmail node): n8n displays an OAuth Redirect URL at the top of the form, something like https://your-instance.example.com/rest/oauth2-credential/callback. Copy that URL exactly as is and paste it into the authorized redirect URIs on the Google side. The slightest deviation — http instead of https, a stray trailing slash, a different port, localhost on one side and a domain on the other — will trigger the redirect_uri_mismatch error at connection time.

Confirm: Google hands you a client ID and a client secret. Treat that secret like a password — our article on securing credentials in n8n explains why and how to protect it.

Step 5: connect the credential in n8n

Back in n8n: paste the client ID and client secret into the credential's matching fields, save, then click Sign in with Google. A Google window opens: pick the account (the one added as a test user if the app is in testing mode), accept the "unverified app" warning if it shows up, tick the requested permissions, and confirm. The window closes and the credential shows as connected.

Repeat only this step 5 for each service: a Google Sheets OAuth2 credential, a Google Drive OAuth2 credential, a Google Calendar OAuth2 credential — all with the same client ID and client secret, each with its own "Sign in with Google" (the requested scopes differ per service).

The self-hosted case: HTTPS is mandatory

On n8n Cloud, the OAuth Redirect URL is clean out of the box. On a self-hosted instance, it's built from the WEBHOOK_URL environment variable (or the configured host as a fallback). Two practical consequences:

• Google requires an HTTPS redirect URI (localhost aside). An instance only reachable at http://server-ip:5678 won't be able to complete the flow cleanly: you need a domain name and a TLS certificate, which our guide on HTTPS and domain names with Traefik or Caddy covers.
• The WEBHOOK_URL variable must point to that public domain, otherwise n8n will display an incorrect Redirect URL. Our environment variables guide details how to set it.

Common pitfalls

• redirect_uri_mismatch error when clicking "Sign in with Google". The URI pasted on the Google side doesn't match the one displayed by n8n character for character. Copy the OAuth Redirect URL straight from the n8n credential (don't retype it by hand), check the protocol, the domain, the port and the absence of an extra trailing slash. On self-hosted, verify that WEBHOOK_URL points to your public HTTPS domain.
• Credential expiring after 7 days. The classic symptom of an app left in testing mode: Google then invalidates the refresh token after 7 days, and n8n can no longer renew access. Push the app to production on the consent screen, then reconnect the credential one last time.
• Insufficient scopes. If a node fails with a permission error even though the connection succeeded, the credential was probably authorized before a scope was added, or a permission checkbox was unticked on the consent screen. Reconnect the credential and accept all the requested permissions.
• "Google hasn't verified this app" screen. Intimidating but not a blocker for personal use: a link in the warning's advanced settings lets you continue to the app. Formal verification is only required to distribute the app to external users.
• API not enabled in the project. The OAuth connection succeeds, but the node's first call fails: check that the relevant service's API (Gmail API, Sheets API, and so on) is indeed enabled in the project's API library.
• Missing test user. In testing mode, an account not listed among the test users is denied access at the Google sign-in screen, before the consent screen even appears.

And beyond Google?

The good news is that this learning is reusable: the logic is identical for Microsoft (Azure), Slack, HubSpot and most modern services. You register an application with the provider, declare n8n's OAuth Redirect URL, retrieve a client ID and a client secret, and paste them into the credential. Only the console names and a few screen options change. Once you've mastered the Google flow, the next ones take a few minutes.

Going further

A clean Google OAuth2 credential — app in production, persistent refresh token, complete scopes — is the foundation of every serious Gmail workflow. It's exactly the prerequisite of the workflows in the AI Inbox Pack (€79), which sort, classify and pre-draft your email replies: they assume a Gmail OAuth2 credential configured as described in this guide, and then run without intervention. And before multiplying credentials on your instance, take the time to read our article on securing API credentials in n8n: encryption, the instance key and sharing best practices are covered there in detail.