How to set up OAuth credentials in n8n

This tutorial guides you through setting up OAuth2 credentials in n8n for secure authentication with external services like Google, Microsoft, or GitHub. It's aimed at technical users building automations who already know n8n basics and need precise steps for configuring OAuth flows, including redirect URLs, token refresh, and credential security.

Why this matters

OAuth2 credentials in n8n enable secure access to third-party APIs without exposing sensitive tokens in workflows, avoiding the common trap of manual token management that leads to expired sessions or security breaches. By setting them up correctly, you ensure reliable automation flows that handle token refresh automatically, reducing downtime and compliance risks in production environments.

Step-by-step

1. Open your n8n instance and navigate to the Credentials section from the sidebar menu. Click the Add Credential button, then search for and select the OAuth2 API credential type, which serves as the base for most providers like Google or GitHub.
2. Enter a descriptive name for the credential, such as Google OAuth for Sheets, and choose whether it's for a specific account (per-user) or shared across the team. For shared use, ensure your n8n instance supports multi-user mode to avoid permission conflicts.
3. Fill in the core OAuth2 details: paste the Client ID and Client Secret from your provider's developer console (e.g., Google Cloud Console). Set the Grant Type to Authorization Code for standard flows, and specify the Authorization URL and Access Token URL – for Google, these are https://accounts.google.com/o/oauth2/v2/auth and https://oauth2.googleapis.com/token, respectively.
4. Configure the Scope field with the required permissions, such as https://www.googleapis.com/auth/spreadsheets for Google Sheets access. Use a space-separated list if multiple scopes are needed, and refer to the provider's documentation for exact strings to prevent authentication failures.
5. Set the Auth URI Query Parameters if required by the provider, like access_type=offline&prompt=consent for Google to enable refresh tokens. Then, define the Redirect URL – this must match exactly what you registered in the provider's console, typically https://your-n8n-instance.com/rest/oauth2-credential/callback for self-hosted n8n.
6. Under Authentication, select Body for POST requests and ensure Refresh Token is enabled by providing the Refresh Token URL (same as Access Token URL for most providers). This allows n8n to automatically refresh expired tokens without manual intervention.
7. Click Connect my account to initiate the OAuth flow. n8n will redirect you to the provider's login page; authorise the app, grant permissions, and return to n8n. You should see a success message with the retrieved access token details.
8. Test the credential by creating a simple workflow with a relevant node, like the Google Sheets node, and selecting your new credential. Execute the node to verify it fetches data without errors, confirming token refresh works if you wait for expiry.
9. Secure the credential: enable encryption in n8n settings if self-hosting, and avoid storing secrets in version control. For production, use environment variables for client secrets via n8n's config options.

Worked example

Consider a workflow that automates syncing GitHub issues to a Google Sheet for team reporting. Start with a Schedule Trigger node set to run daily, connected to a GitHub node using OAuth2 credentials configured for repo scope to fetch open issues from a repository via the List Issues operation.

Next, add a Google Sheets node with your Google OAuth2 credential (scopes: spreadsheets), using the Append operation to add fetched issue data – title, assignee, and status – to a sheet named Issue Tracker. Include an IF node beforehand to filter only high-priority issues based on labels.

Finally, end with an Email node (using n8n's built-in SMTP) to notify the team of updates. This end-to-end flow relies on OAuth for secure, token-managed access: GitHub handles repo reads, Google manages sheet writes, and automatic refresh ensures the workflow runs reliably without interruptions, even after token expiry.

Common pitfalls

• Symptom: Redirect URI mismatch error during authorisation. Fix: Ensure the redirect URL in n8n exactly matches the one registered in the provider's console, including protocol (https) and path; test by copying directly from n8n's callback URL display.
• Symptom: Token refresh fails, causing API calls to 401 after initial success. Fix: Verify the refresh token URL and include prompt=consent in auth parameters for providers like Google; re-authorise if no refresh token was issued initially.
• Symptom: Insufficient scopes lead to partial data or access denied. Fix: Double-check the provider's API docs for exact scope strings and add them space-separated; test with a minimal workflow to isolate permission issues before scaling.
• Symptom: Credentials work in testing but fail in production due to IP restrictions. Fix: Whitelist your n8n server's IP in the provider's security settings, or use a proxy if self-hosting behind a firewall.
• Symptom: Shared credentials expose tokens across users unexpectedly. Fix: Switch to per-account mode in n8n for sensitive automations, and audit access logs to monitor usage.

Related workflows in the catalog

Explore n8n's workflow catalog for ready-to-import templates that use OAuth2, such as the Google Sheets to Slack notifier, which uses Google and Slack OAuth for automated updates. With over 14,000+ importable workflows, you can adapt ones like GitHub Issue Sync to Microsoft Teams to fit your needs, incorporating Microsoft Graph OAuth for enterprise integrations.

Search the catalog by provider (e.g., "OAuth Google") to find variations that handle token refresh in multi-step automations, saving setup time for complex flows.