Skip to main content
GatePass supports multiple authentication methods: Email/Password, OAuth (Google, Twitter), and Web3 Wallet authentication.

​
Authentication Methods

GatePass provides a flexible authentication system that supports both traditional and modern authentication methods:
  • Email/Password: Classic username and password authentication with bcrypt hashing
  • Google OAuth 2.0: Social login via Google accounts
  • Twitter OAuth 1.0a: Social login via Twitter accounts
  • Web3 Wallet: Ethereum wallet-based authentication (coming soon)

​
JWT Token Flow

GatePass uses a dual-token authentication system for enhanced security:
1

Access Token

Short-lived JWT token (15 minutes) used for API requests. Contains user ID, email, and role.
2

Refresh Token

Long-lived token (7 days) stored in HTTP-only cookie. Used to obtain new access tokens.

​
Token Structure

// Access Token Payload
{
  userId: string,
  email: string,
  role: 'USER' | 'ORGANIZER' | 'ADMIN',
  iat: number,
  exp: number
}

// Refresh Token Payload
{
  userId: string,
  iat: number,
  exp: number
}

​
Email/Password Authentication

​
Registration

Create a new user account with email and password. 
const response = await fetch('https://api.gatepass.app/api/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'SecurePass123',
    name: 'John Doe',
    walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',  // Optional
    role: 'USER'  // or 'ORGANIZER'
  })
});

const data = await response.json();
console.log(data.token);  // Access token
Password Requirements: Minimum 8 characters with at least one uppercase letter, one lowercase letter, and one number.

​
Login

Authenticate an existing user. 
const response = await fetch('https://api.gatepass.app/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  credentials: 'include',  // Important: Include cookies
  body: JSON.stringify({
    email: '[email protected]',
    password: 'SecurePass123'
  })
});

const data = await response.json();
localStorage.setItem('accessToken', data.token);

​
Refresh Token

Obtain a new access token using the refresh token. 
const response = await fetch('https://api.gatepass.app/api/auth/refresh-token', {
  method: 'POST',
  credentials: 'include'  // Sends the refresh token cookie
});

const data = await response.json();
localStorage.setItem('accessToken', data.token);
The refresh token is stored in an HTTP-only cookie for security. You cannot access it via JavaScript.

​
Google OAuth Integration

Integrate Google Sign-In for seamless authentication.

​
Configuration

Set up Google OAuth credentials in your .env file:
.env
GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_google_client_secret
CORS_ORIGIN=http://localhost:5173

​
Implementation

// Redirect user to Google OAuth
window.location.href = 'https://api.gatepass.app/api/auth/google';

// Handle callback on your frontend
const urlParams = new URLSearchParams(window.location.search);
const token = urlParams.get('token');

if (token) {
  localStorage.setItem('accessToken', token);
  // Redirect to dashboard
  window.location.href = '/dashboard';
}

​
Twitter OAuth Integration

Integrate Twitter Sign-In for social authentication.

​
Configuration

Set up Twitter OAuth credentials:
.env
TWITTER_CONSUMER_KEY=your_twitter_consumer_key
TWITTER_CONSUMER_SECRET=your_twitter_consumer_secret
CORS_ORIGIN=http://localhost:5173

​
Implementation

// Redirect user to Twitter OAuth
window.location.href = 'https://api.gatepass.app/api/auth/twitter';

// Handle callback (same as Google)
const urlParams = new URLSearchParams(window.location.search);
const token = urlParams.get('token');

if (token) {
  localStorage.setItem('accessToken', token);
  window.location.href = '/dashboard';
}
Twitter doesn’t always provide email addresses. Users may need to grant explicit permission or use email/password registration.

​
Protected API Requests

Include the access token in your API requests. 
const response = await fetch('https://api.gatepass.app/api/events', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('accessToken')}`,
    'Content-Type': 'application/json'
  }
});

const events = await response.json();

​
Get Current User

Retrieve the authenticated user’s profile. 
const response = await fetch('https://api.gatepass.app/api/auth/me', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('accessToken')}`
  }
});

const { user } = await response.json();

​
Logout

Invalidate the current session and clear tokens. 
const response = await fetch('https://api.gatepass.app/api/auth/logout', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('accessToken')}`
  },
  credentials: 'include'
});

if (response.ok) {
  localStorage.removeItem('accessToken');
  window.location.href = '/login';
}

​
Security Best Practices

Token Storage

Store access tokens in localStorage or sessionStorage. Never store refresh tokens in JavaScript-accessible storage.

HTTPS Only

Always use HTTPS in production. Refresh tokens are set with secure flag in production mode.

Token Rotation

Implement automatic token refresh when access tokens expire. Use interceptors to handle 401 responses.

Password Validation

Enforce strong password requirements: minimum 8 characters with uppercase, lowercase, and numbers.

​
Environment Variables

Required environment variables for authentication:
.env
# JWT Secrets
JWT_SECRET=your_secure_jwt_secret_min_32_chars
JWT_REFRESH_SECRET=your_secure_refresh_secret_min_32_chars

# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_google_client_secret

# Twitter OAuth
TWITTER_CONSUMER_KEY=your_twitter_consumer_key
TWITTER_CONSUMER_SECRET=your_twitter_consumer_secret

# Frontend URL for OAuth redirects
CORS_ORIGIN=http://localhost:5173
FRONTEND_URL=http://localhost:5173

# Node Environment
NODE_ENV=production

​
Error Handling

Common authentication errors and their meanings:
Status CodeErrorDescription
400Invalid email formatEmail validation failed
400Password must be at least 8 charactersPassword too short
401Invalid email or passwordLogin credentials incorrect
401Invalid refresh tokenRefresh token expired or invalid
409User already existsEmail or wallet address already registered
For complete authentication flow implementation, refer to:
  • ~/workspace/source/src/packages/server/src/routes/auth.ts
  • ~/workspace/source/src/packages/server/src/config/passport.ts
  • ~/workspace/source/src/packages/server/src/utils/auth.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us