Skip to main content

​
Overview

GatePass supports OAuth 2.0 authentication with Google and Twitter. Social authentication allows users to sign in using their existing social media accounts without creating a separate password.

​
Supported Providers

Google OAuth

Sign in with Google account

Twitter OAuth

Sign in with Twitter account

​
Google Authentication

​
Initiate Google OAuth Flow

GET /api/auth/google
Redirects the user to Google’s OAuth consent screen where they can authorize GatePass to access their profile and email. Scopes Requested:
  • profile: Access to user’s basic profile information
  • email: Access to user’s email address

​
Example

cURL
curl -L https://api.gatepass.com/api/auth/google
Or redirect users from your frontend: 
window.location.href = 'https://api.gatepass.com/api/auth/google';

​
Google OAuth Callback

GET /api/auth/google/callback
This endpoint is called automatically by Google after the user authorizes the application. It:
  1. Verifies the OAuth code from Google
  2. Creates or updates the user account
  3. Generates JWT access and refresh tokens
  4. Redirects to the frontend with the access token
Redirect URL: 
{FRONTEND_URL}/auth/callback?token={access_token}
Error Redirect: If authentication fails, the user is redirected to: 
{FRONTEND_URL}/login

​
Twitter Authentication

​
Initiate Twitter OAuth Flow

GET /api/auth/twitter
Redirects the user to Twitter’s OAuth authorization screen.

​
Example

cURL
curl -L https://api.gatepass.com/api/auth/twitter
Or redirect users from your frontend: 
window.location.href = 'https://api.gatepass.com/api/auth/twitter';

​
Twitter OAuth Callback

GET /api/auth/twitter/callback
This endpoint is called automatically by Twitter after the user authorizes the application. The flow is similar to Google’s callback:
  1. Verifies the OAuth token from Twitter
  2. Creates or updates the user account
  3. Generates JWT access and refresh tokens
  4. Redirects to the frontend with the access token
Redirect URL: 
{FRONTEND_URL}/auth/callback?token={access_token}

​
OAuth Callback Handling

​
Frontend Implementation

Handle the OAuth callback in your frontend application: 
// Example: React component for /auth/callback route
import { useEffect } from 'react';
import { useNavigate, useSearchParams } from 'react-router-dom';

function AuthCallback() {
  const [searchParams] = useSearchParams();
  const navigate = useNavigate();
  
  useEffect(() => {
    const token = searchParams.get('token');
    
    if (token) {
      // Store the access token
      localStorage.setItem('accessToken', token);
      
      // Fetch user details
      fetch('https://api.gatepass.com/api/auth/me', {
        headers: {
          'Authorization': `Bearer ${token}`
        }
      })
      .then(res => res.json())
      .then(data => {
        // Store user data and redirect
        localStorage.setItem('user', JSON.stringify(data.user));
        navigate('/dashboard');
      })
      .catch(() => {
        navigate('/login');
      });
    } else {
      navigate('/login');
    }
  }, [searchParams, navigate]);
  
  return <div>Authenticating...</div>;
}

​
Session Management

​
Token Structure

After successful OAuth authentication, users receive:
  1. Access Token (returned in redirect URL)
    • Valid for 15 minutes
    • Contains user ID, email, and role
    • Used for API authentication
  2. Refresh Token (stored in HttpOnly cookie)
    • Valid for 7 days
    • Stored securely in database
    • Used to obtain new access tokens
The refresh token is automatically set as an HttpOnly cookie with these properties: 
{
  httpOnly: true,           // Prevents JavaScript access
  secure: true,             // HTTPS only (in production)
  sameSite: 'strict',       // CSRF protection
  maxAge: 604800000         // 7 days in milliseconds
}

​
User Account Creation

When a user authenticates via OAuth for the first time:
  1. A new user account is created with:
    • Email from OAuth provider
    • Name from OAuth provider profile
    • Default role: USER
    • No password (OAuth users don’t need passwords)
  2. If the user already exists (matched by email):
    • The existing account is used
    • Profile information may be updated

​
Environment Configuration

To enable OAuth authentication, configure these environment variables: 
# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_CALLBACK_URL=https://api.gatepass.com/api/auth/google/callback

# Twitter OAuth
TWITTER_CONSUMER_KEY=your_twitter_consumer_key
TWITTER_CONSUMER_SECRET=your_twitter_consumer_secret
TWITTER_CALLBACK_URL=https://api.gatepass.com/api/auth/twitter/callback

# Frontend URL for redirects
CORS_ORIGIN=https://app.gatepass.com

​
Security Considerations

  • OAuth sessions use the same security measures as email/password authentication
  • Refresh tokens are stored securely in HttpOnly cookies
  • Access tokens have short expiration times (15 minutes)
  • All tokens are signed with JWT secrets
  • OAuth accounts are linked by email address
  • Users cannot have multiple accounts with the same email
  • If a user signs up with email/password, they can later use OAuth with the same email
  • Only necessary scopes are requested (profile and email)
  • OAuth provider tokens are not stored
  • Users can revoke access from their OAuth provider settings

​
Error Handling

If OAuth authentication fails:
  • User is redirected to /login on the frontend
  • Common failure reasons:
    • User denied authorization
    • Invalid OAuth configuration
    • Network errors
    • Email already exists with different provider

​
Example: Complete OAuth Flow

Build docs developers (and LLMs) love

Get started for freeTalk to us