Skip to main content
GET
/
api
/
services
/
[id]
/
connect
Connect Service to Gmail
curl --request GET \
  --url 'https://api.example.com/api/services/[id]/connect'
Initiates the Google OAuth 2.0 flow to connect a service account to Gmail. This enables the service to read and send emails through the Gmail API.

​
Authentication

Requires admin session. Only users with admin permission can connect services to Gmail.
This endpoint requires admin privileges. Regular users will receive a 403 Forbidden response.

​
Path parameters

​
id
string
required
The unique identifier of the service to connect

​
OAuth flow

This endpoint initiates a multi-step OAuth process:
  1. Request: User navigates to /api/services/[id]/connect
  2. State generation: Server creates encrypted state with service ID and nonce
  3. Redirect: User is redirected to Google OAuth consent screen
  4. Authorization: User grants Gmail permissions
  5. Callback: Google redirects to /api/services/oauth/callback
  6. Token exchange: Server exchanges code for access and refresh tokens
  7. Storage: Tokens are stored in the database
  8. Complete: User is redirected back to the application

​
Required OAuth scopes

The connection requests the following Gmail API scopes:
  • https://www.googleapis.com/auth/gmail.readonly - Read emails
  • https://www.googleapis.com/auth/gmail.send - Send emails

​
Response

This endpoint returns a 302 redirect to Google’s OAuth authorization URL.

​
Redirect parameters

  • client_id - Your Google OAuth client ID
  • redirect_uri - Your callback URL
  • response_type - Always code
  • access_type - Always offline (to obtain refresh token)
  • prompt - Always consent (to ensure refresh token is granted)
  • scope - Gmail read and send permissions
  • state - Encrypted state containing service ID
A secure HTTP-only cookie named gmail_oauth_state is set containing: 
{
  "serviceId": "service-123",
  "nonce": "uuid-v4",
  "ts": 1709308800000
}
Cookie properties:
  • httpOnly: true
  • sameSite: lax
  • secure: true (on HTTPS)
  • maxAge: 600 (10 minutes)
  • path: /

​
Error responses

// Response: Redirect to /login
// Reason: No active session

​
Code examples

curl --request GET \
  --url 'https://your-domain.com/api/services/service-123/connect' \
  --cookie 'authjs.session-token=YOUR_ADMIN_SESSION_TOKEN' \
  --location  # Follow redirects

​
Environment variables

Required environment variables: 
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
See the OAuth Setup Guide for instructions on obtaining Google OAuth credentials.

​
Implementation details

The endpoint:
  1. Validates admin session via requireAdminSession()
  2. Reads GOOGLE_CLIENT_ID from environment
  3. Constructs OAuth authorization URL with required parameters
  4. Generates and encrypts state parameter
  5. Sets secure state cookie
  6. Redirects user to Google OAuth consent screen

​
After connection

Once connected, the service’s refreshToken field is populated in the database. This enables:
  • Syncing emails from Gmail
  • Sending emails through the Gmail API
  • Automatic token refresh when access tokens expire
After successful connection, use the Sync endpoint to import emails from Gmail.

Build docs developers (and LLMs) love

Get started for freeTalk to us