BuildWithMatija
Get In Touch
  1. Home
  2. Blog
  3. Payload
  4. Google Drive OAuth for Payload CMS: Complete Guide

Google Drive OAuth for Payload CMS: Complete Guide

Step-by-step setup for multi-tenant Google Drive OAuth in Payload CMS — token persistence, tenant-aware storage, and…

13th March 2026·Updated on:6th April 2026·MŽMatija Žiberna·
Payload
Google Drive OAuth for Payload CMS: Complete Guide

Need Help Making the Switch?

Moving to Next.js and Payload CMS? I offer advisory support on an hourly basis.

Book Hourly Advisory

Related Posts:

  • •Payload CMS Admin UI: Custom Components with @payloadcms/ui
  • •Payload Import Triggers: 4 Essential Ways to Queue Imports
  • •rclone Google Drive client_id: Create Your Own OAuth App

I was wiring Google Drive into a multi-tenant Payload CMS app and expected OAuth to be the easy part. The Google consent screen worked quickly, but callback persistence failed on tenant/user constraints and then failed again on migration collisions. This guide is the exact implementation that ended up working in production-style conditions, including the fixes for the errors you are most likely to hit.

By the end, you will have a working Google Drive OAuth flow in Payload CMS with:

  • connect/reconnect/disconnect from admin settings,
  • tenant-aware connection storage,
  • token persistence in PostgreSQL,
  • and a clean callback pipeline that survives real schema constraints.

Step 1: Configure Google Cloud OAuth Correctly

Start in Google Cloud Console with a dedicated project (for example, aArheko) and enable Google Drive API.

Then create OAuth client ID (Web application) and define both JavaScript origins and redirect URIs.

For your setup, this is valid and complete:

  • Authorized JavaScript origins:
    • https://www.arheko.eu
    • http://localhost:3000
    • https://23e7-46-124-201-0.ngrok-free.app
  • Authorized redirect URIs:
    • https://www.arheko.eu/api/integrations/google/callback
    • https://arheko.eu/api/integrations/google/callback
    • http://localhost:3000/api/integrations/google/callback
    • https://23e7-46-124-201-0.ngrok-free.app/api/integrations/google/callback

The critical rule is exact matching. If callback URL differs by domain, scheme, or path, token exchange fails.

On scopes, keep this minimal unless you have a hard requirement for broader access. For this integration, these scopes are enough:

  • openid
  • email
  • profile
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/drive.metadata.readonly

If you add broad scopes like drive or docs, you increase review and consent complexity without helping basic integration setup.

Step 2: Add Environment Variables

Create/update your env file with OAuth credentials.

# .env.local
GOOGLE_OAUTH_CLIENT_ID=your_client_id.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your_client_secret
GOOGLE_OAUTH_REDIRECT_URI=http://localhost:3000/api/integrations/google/callback

# Optional (recommended for production):
GOOGLE_OAUTH_TOKEN_ENCRYPTION_KEY=replace_with_strong_secret

GOOGLE_OAUTH_REDIRECT_URI is optional in this implementation because fallback logic derives it from server URL/origin, but explicit is better for predictability.

Step 3: Install the Google SDK

Install the official Node SDK used by the server routes.

pnpm add googleapis

Step 4: Create a Payload Collection for OAuth Connections

Create a dedicated collection to store provider metadata, user/tenant mapping, and tokens.

// File: src/payload/collections/configuration/google-connections/index.ts
import type { CollectionConfig } from 'payload';

export const GoogleConnections: CollectionConfig = {
  slug: 'google-connections',
  indexes: [
    {
      fields: ['provider', 'activeTenantId', 'payloadUserId', 'googleAccountEmail'],
      unique: true,
    },
  ],
  fields: [
    { name: 'provider', type: 'select', required: true, defaultValue: 'google-drive', options: [{ label: 'Google Drive', value: 'google-drive' }] },
    { name: 'tenant', type: 'relationship', relationTo: 'tenants' },
    { name: 'user', type: 'relationship', relationTo: 'users' },
    { name: 'payloadUserId', type: 'number', required: true, index: true },
    { name: 'activeTenantId', type: 'number', required: true, index: true },
    { name: 'googleAccountEmail', type: 'email', required: true, index: true },
    { name: 'googleAccountId', type: 'text' },
    {
      name: 'scopes',
      type: 'array',
      fields: [{ name: 'value', type: 'text', required: true }],
    },
    { name: 'accessToken', type: 'textarea', access: { read: () => false } },
    { name: 'refreshToken', type: 'textarea', access: { read: () => false } },
    { name: 'tokenType', type: 'text' },
    { name: 'expiryDate', type: 'date' },
    { name: 'isActive', type: 'checkbox', required: true, defaultValue: true, index: true },
    { name: 'lastSyncedAt', type: 'date' },
    { name: 'lastError', type: 'textarea' },
  ],
};

This structure gives you two important things. First, relation fields (tenant, user) for admin readability. Second, stable numeric ownership keys (activeTenantId, payloadUserId) for route filtering without relation validation surprises in multi-tenant flows.

Then register this collection in:

  • src/payload/collections/index.ts
  • payload.config.ts
  • src/payload/access-control/visibility.ts

Step 5: Add OAuth Helper Module

Create a helper that centralizes OAuth client creation and token encryption.

// File: src/lib/google/oauth.ts
import crypto from 'node:crypto';
import { google } from 'googleapis';

export const GOOGLE_DRIVE_SCOPES = [
  'openid',
  'email',
  'profile',
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly',
] as const;

export function getGoogleOAuthEnv(origin?: string) {
  const clientId = (process.env.GOOGLE_OAUTH_CLIENT_ID || '').trim();
  const clientSecret = (process.env.GOOGLE_OAUTH_CLIENT_SECRET || '').trim();
  const configuredRedirectUri = (process.env.GOOGLE_OAUTH_REDIRECT_URI || '').trim();
  const base = (process.env.NEXT_PUBLIC_SERVER_URL || origin || '').replace(/\/$/, '');
  const redirectUri = configuredRedirectUri || `${base}/api/integrations/google/callback`;

  if (!clientId || !clientSecret || !redirectUri) {
    throw new Error('Missing Google OAuth env configuration');
  }

  return { clientId, clientSecret, redirectUri };
}

export function createGoogleOAuthClient(env: { clientId: string; clientSecret: string; redirectUri: string }) {
  return new google.auth.OAuth2(env.clientId, env.clientSecret, env.redirectUri);
}

The key benefit here is route simplicity. Each route imports the same logic for env parsing and OAuth client creation, so behavior is consistent between local, ngrok, and production.

Step 6: Implement OAuth Routes

You need four routes.

6.1 Start route

// File: src/app/api/integrations/google/start/route.ts
const authorizationUrl = client.generateAuthUrl({
  access_type: 'offline',
  prompt: 'consent',
  scope: [...GOOGLE_DRIVE_SCOPES],
  state,
  include_granted_scopes: true,
});

return NextResponse.redirect(authorizationUrl);

This route authenticates the current user, resolves active tenant, stores short-lived cookies (state, tenant, returnTo), then redirects to Google.

6.2 Callback route

// File: src/app/api/integrations/google/callback/route.ts
const tokenResponse = await client.getToken(code);
client.setCredentials(tokenResponse.tokens);

const profile = await fetchGoogleProfile(client);

const connectionData = {
  provider: 'google-drive' as const,
  user: user.id,
  tenant: tenantId,
  payloadUserId: user.id,
  activeTenantId: tenantId,
  googleAccountEmail: profile.email,
  accessToken: encryptToken(tokens.access_token || null),
  refreshToken: encryptToken(nextRefreshToken),
  tokenType: tokens.token_type || null,
  expiryDate: tokens.expiry_date ? new Date(tokens.expiry_date).toISOString() : null,
  isActive: true,
};

This is the most important step. It validates state, exchanges the code, and persists the connection. In this implementation we intentionally write both relation and numeric ownership fields because that proved most stable with existing schema constraints.

6.3 Status route

GET /api/integrations/google/status returns a safe payload (connected, email, scopes, expiry, updatedAt) without exposing tokens.

6.4 Disconnect route

POST /api/integrations/google/disconnect attempts token revoke and then marks connection inactive while clearing stored tokens.

Step 7: Add Admin Settings UI

Add an Integrations section under your admin settings and a nested Google page.

// File: src/app/admin/settings/integrations/google/page.tsx
<Button asChild>
  <Link href="/api/integrations/google/start?returnTo=/admin/settings/integrations/google">
    {isConnected ? 'Reconnect Google Drive' : 'Connect Google Drive'}
  </Link>
</Button>

{isConnected ? (
  <form method="post" action="/api/integrations/google/disconnect">
    <Button type="submit" variant="outline">Disconnect</Button>
  </form>
) : null}

The page also reads current connection from Payload and renders account/scopes/expiry so users can see the actual integration state.

Step 8: Run Migrations and Generate Types

Run the standard Payload flow:

pnpm payload generate:types
pnpm payload migrate

If your project script uses cross-env and that package is not present, invoke Payload CLI directly as shown above.

Debugging Notes from Real Failures

This setup hit three real issues during implementation.

First, callback failed with ValidationError: User is invalid. The fix was to introduce payloadUserId and activeTenantId and use those for ownership filters, while still writing relation fields for compatibility.

Second, migration failed because custom tenantId / userId names collided with relation-backed tenant_id / user_id database columns. Renaming to activeTenantId / payloadUserId removed the collision.

Third, callback insert failed because google_connections.user_id was NOT NULL in the existing schema and insert attempted default/null. Explicitly writing user: user.id fixed that insert path immediately.

If you see callback errors with SQL details, decode the details= query param in your redirected URL. It usually reveals the exact column/constraint mismatch in seconds.

Final Checklist

  • Google Drive API enabled in Google Cloud.
  • OAuth client configured with exact redirect URIs for all environments.
  • Env vars set (GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, redirect URI).
  • googleapis installed.
  • google-connections collection registered.
  • OAuth routes implemented.
  • Admin integration page wired.
  • Migrations applied.
  • Connect flow tested from /admin/settings/integrations/google.

At this point, your OAuth foundation is complete and you can build actual Drive operations (file listing, upload, sync) on top of a stable connection model.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

📚 Comprehensive Payload CMS Guides

Detailed Payload guides with field configuration examples, custom components, and workflow optimization tips to speed up your CMS development process.

No spam. Unsubscribe anytime.

📄View markdown version
0

Frequently Asked Questions

Comments

Leave a Comment

Your email will not be published

Stay updated! Get our weekly digest with the latest learnings on NextJS, React, AI, and web development tips delivered straight to your inbox.

10-2000 characters

• Comments are automatically approved and will appear immediately

• Your name and email will be saved for future comments

• Be respectful and constructive in your feedback

• No spam, self-promotion, or off-topic content

No comments yet

Be the first to share your thoughts on this post!

Matija Žiberna
Matija Žiberna
Full-stack developer, co-founder

I'm Matija Žiberna, a self-taught full-stack developer and co-founder passionate about building products, writing clean code, and figuring out how to turn ideas into businesses. I write about web development with Next.js, lessons from entrepreneurship, and the journey of learning by doing. My goal is to provide value through code—whether it's through tools, content, or real-world software.

You might be interested in

Payload CMS Admin UI: Custom Components with @payloadcms/ui
Payload CMS Admin UI: Custom Components with @payloadcms/ui

16th October 2025

Payload Import Triggers: 4 Essential Ways to Queue Imports
Payload Import Triggers: 4 Essential Ways to Queue Imports

2nd April 2026

rclone Google Drive client_id: Create Your Own OAuth App
rclone Google Drive client_id: Create Your Own OAuth App

31st March 2026

Table of Contents

  • Step 1: Configure Google Cloud OAuth Correctly
  • Step 2: Add Environment Variables
  • Step 3: Install the Google SDK
  • Step 4: Create a Payload Collection for OAuth Connections
  • Step 5: Add OAuth Helper Module
  • Step 6: Implement OAuth Routes
  • 6.1 Start route
  • 6.2 Callback route
  • 6.3 Status route
  • 6.4 Disconnect route
  • Step 7: Add Admin Settings UI
  • Step 8: Run Migrations and Generate Types
  • Debugging Notes from Real Failures
  • Final Checklist
On this page:
  • Step 1: Configure Google Cloud OAuth Correctly
  • Step 2: Add Environment Variables
  • Step 3: Install the Google SDK
  • Step 4: Create a Payload Collection for OAuth Connections
  • Step 5: Add OAuth Helper Module
Build With Matija Logo

Build with Matija

Modern websites, content systems, and AI workflows built for long-term growth.

Services

  • Headless CMS Websites
  • Next.js & Headless CMS Advisory
  • AI Systems & Automation
  • Website & Content Audit
  • Resources

    • Case Studies
    • How I Work
    • Blog
    • CMS Hub
    • E-commerce Hub
    • Dashboard

    Headless CMS

    • Payload CMS Developer
    • CMS Migration
    • Payload vs Sanity
    • Payload vs WordPress
    • Payload vs Contentful

    Get in Touch

    Ready to modernize your stack? Let's talk about what you're building.

    Book a discovery callContact me →
    © 2026BuildWithMatija•All rights reserved