OAuth Authentication - Reservations

Overview

The Reservations API supports OAuth 2.0 authentication with Google and Facebook providers. OAuth allows users to authenticate using their existing social media accounts without creating a new password.

Supported Providers

Google - OAuth 2.0 with OpenID Connect
Facebook - OAuth 2.0 with Graph API

OAuth Flow

The OAuth authentication flow follows these steps:

Initiate: User clicks login button, redirects to provider’s authorization page
Authorize: User grants permissions on provider’s website
Callback: Provider redirects back to API with authorization code
Exchange: API exchanges code for access token and fetches user info
Authenticate: API creates or finds user account and returns JWT tokens

Google OAuth

Redirect the user to Google’s authorization page.

curl -X GET https://api.example.com/api/v1/auth/oauth/google

Endpoint

GET /api/v1/auth/oauth/google

endpoint

Initiate Google OAuth flow

Response

Returns a 307 Temporary Redirect to Google’s authorization URL with:

Location

header

Google OAuth authorization URL with state parameter

oauth-state - CSRF protection state token

OAuth Configuration

Scopes: email, profile
Access Type: Offline (allows refresh token)
Endpoint: Google OAuth 2.0 endpoints
Redirect URI: http://localhost:8080/api/v1/auth/callback/google

Step 2: Google Callback

After user authorization, Google redirects to this callback endpoint.

Endpoint

GET /api/v1/auth/oauth/google/callback

endpoint

Handle Google OAuth callback

Query Parameters

code

string

required

Authorization code from Google

state

string

required

State parameter for CSRF validation

Response

On success:

Validates state parameter against cookie
Exchanges authorization code for access token
Fetches user profile from Google
Creates new user or finds existing user by provider ID
Returns JWT tokens as HTTP-only cookies
Redirects to http://localhost:8080/ with 308 Permanent Redirect

jwt-access - Access token cookie

jwt-refresh - Refresh token cookie

Location

header

Redirect to application homepage

Google User Profile

The API fetches the following information from Google’s OpenID Connect endpoint:

{
  "sub": "google-user-id",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://...",
  "email": "[email protected]",
  "email_verified": true,
  "locale": "en"
}

Error Responses

400 Bad Request

Invalid state parameter or OAuth exchange error

500 Internal Server Error

Unexpected error during OAuth flow or user creation

Facebook OAuth

Redirect the user to Facebook’s authorization page.

curl -X GET https://api.example.com/api/v1/auth/oauth/facebook

Endpoint

GET /api/v1/auth/oauth/facebook

endpoint

Initiate Facebook OAuth flow

Response

Returns a 307 Temporary Redirect to Facebook’s authorization URL with:

Location

header

Facebook OAuth authorization URL with state parameter

oauth-state - CSRF protection state token

OAuth Configuration

Scopes: email, public_profile
Access Type: Offline (allows refresh token)
Endpoint: Facebook OAuth 2.0 endpoints
Redirect URI: http://localhost:8080/api/v1/auth/callback/facebook

Step 2: Facebook Callback

After user authorization, Facebook redirects to this callback endpoint.

Endpoint

GET /api/v1/auth/oauth/facebook/callback

endpoint

Handle Facebook OAuth callback

Query Parameters

code

string

required

Authorization code from Facebook

state

string

required

State parameter for CSRF validation

Response

On success:

Validates state parameter against cookie
Exchanges authorization code for access token
Fetches user profile from Facebook Graph API
Creates new user or finds existing user by provider ID
Returns JWT tokens as HTTP-only cookies
Redirects to http://localhost:8080/ with 308 Permanent Redirect

jwt-access - Access token cookie

jwt-refresh - Refresh token cookie

Location

header

Redirect to application homepage

Facebook User Profile

The API fetches the following information from Facebook Graph API v24.0:

{
  "id": "facebook-user-id",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "picture": {
    "data": {
      "url": "https://..."
    }
  }
}

Error Responses

400 Bad Request

Invalid state parameter or OAuth exchange error

500 Internal Server Error

Unexpected error during OAuth flow or user creation

OAuth Configuration

OAuth providers require configuration via environment variables:

Google Configuration

GOOGLE_OAUTH_CLIENT_ID

string

required

Google OAuth 2.0 client ID from Google Cloud Console

GOOGLE_OAUTH_CLIENT_SECRET

string

required

Google OAuth 2.0 client secret from Google Cloud Console

Facebook Configuration

FACEBOOK_OAUTH_CLIENT_ID

string

required

Facebook App ID from Facebook Developers Console

FACEBOOK_OAUTH_CLIENT_SECRET

string

required

Facebook App Secret from Facebook Developers Console

User Account Creation

When a user authenticates via OAuth for the first time:

Check Existing Account: The API checks if a user with the provider ID already exists
Create New User: If not found, creates a new user account with:
- UUID v7 user ID
- First name and last name from OAuth provider
- Email address from OAuth provider
- No password hash (OAuth users don’t have passwords)
- No phone number initially
- Auth provider type (google or facebook)
- Provider ID (unique identifier from OAuth provider)
- JWT refresh version set to 0
Generate Tokens: Creates JWT access and refresh tokens
Return Tokens: Sets tokens as HTTP-only cookies

User Record Example

domain.User{
    Id:                "018c...",  // UUID v7
    FirstName:         "John",
    LastName:          "Doe",
    Email:             "[email protected]",
    PhoneNumber:       nil,       // Not provided by OAuth
    PasswordHash:      nil,       // No password for OAuth users
    JwtRefreshVersion: 0,
    PreferredLang:     nil,
    AuthProvider:      "google",  // or "facebook"
    ProviderId:        "1234567890"
}

Security Considerations

State Parameter

The OAuth state parameter prevents CSRF attacks:

Generation: Random state value is generated when initiating OAuth flow
Storage: State is stored in an HTTP-only cookie
Validation: On callback, the state parameter is validated against the cookie
Error: If validation fails, the request is rejected with a 400 error

Token Security

JWT tokens returned after OAuth authentication have the same security properties as regular JWT login:

HTTP-only cookies (XSS protection)
SameSite: Lax (CSRF protection)
Separate access and refresh tokens
Configurable expiration times

Account Linking

Currently, if a user signs up with email/password and later tries to authenticate with OAuth using the same email:

A separate account is created with the OAuth provider
The system does not automatically link accounts
Users should use the same authentication method they originally signed up with

Future enhancement: The TODO comments in the code suggest adding a prompt to login with the original method if an OAuth user’s email matches an existing account.

Implementation Example

Frontend Integration

// Add OAuth login buttons to your frontend

function loginWithGoogle() {
  // Redirect to initiate Google OAuth flow
  window.location.href = 'https://api.example.com/api/v1/auth/oauth/google';
}

function loginWithFacebook() {
  // Redirect to initiate Facebook OAuth flow
  window.location.href = 'https://api.example.com/api/v1/auth/oauth/facebook';
}

// The OAuth flow will:
// 1. Redirect to provider (Google/Facebook)
// 2. User authorizes on provider's site
// 3. Provider redirects to callback endpoint
// 4. Callback sets JWT cookies and redirects to http://localhost:8080/
// 5. User is now authenticated with JWT tokens in cookies

Backend Configuration

# .env file
GOOGLE_OAUTH_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your-google-client-secret

FACEBOOK_OAUTH_CLIENT_ID=your-facebook-app-id
FACEBOOK_OAUTH_CLIENT_SECRET=your-facebook-app-secret

Redirect URIs

Make sure to configure these redirect URIs in your OAuth provider consoles:

Google Cloud Console: http://localhost:8080/api/v1/auth/callback/google
Facebook Developers Console: http://localhost:8080/api/v1/auth/callback/facebook

Update redirect URIs to use your production domain when deploying to production.

Overview

Merchant API

Booking API

Authentication

Public API

​Overview

​Supported Providers

​OAuth Flow

​Google OAuth

​Step 1: Initiate Google Login

​Endpoint

​Response

​OAuth Configuration

​Step 2: Google Callback

​Endpoint

​Query Parameters

​Response

​Google User Profile

​Error Responses

​Facebook OAuth

​Step 1: Initiate Facebook Login

​Endpoint

​Response

​OAuth Configuration

​Step 2: Facebook Callback

​Endpoint

​Query Parameters

​Response

​Facebook User Profile

​Error Responses

​OAuth Configuration

​Google Configuration

​Facebook Configuration

​User Account Creation

​User Record Example

​Security Considerations

​State Parameter

​Token Security

​Account Linking

​Implementation Example

​Frontend Integration

​Backend Configuration

​Redirect URIs

Build docs developers (and LLMs) love

Overview

Supported Providers

OAuth Flow

Google OAuth

Step 1: Initiate Google Login

Endpoint

Response

OAuth Configuration

Step 2: Google Callback

Endpoint

Query Parameters

Response

Google User Profile

Error Responses

Facebook OAuth

Step 1: Initiate Facebook Login

Endpoint

Response

OAuth Configuration

Step 2: Facebook Callback

Endpoint

Query Parameters

Response

Facebook User Profile

Error Responses

OAuth Configuration

Google Configuration

Facebook Configuration

User Account Creation

User Record Example

Security Considerations

State Parameter

Token Security

Account Linking

Implementation Example

Frontend Integration

Backend Configuration

Redirect URIs