Social Login

Gately supports OAuth authentication with Google and GitHub, allowing users to sign in with their existing accounts.

redirectTo must be on a domain your project owns. Add your site under Allowed Redirect URLs before going live, or sign-in will be rejected.

await gately.loginWithGoogle(options)

Options

Option	Type	Default	Description
`redirectTo`	string	Current URL	URL to redirect after login. Must be an allowed redirect URL

Example

// Simple usage
await gately.loginWithGoogle()

// With redirect
await gately.loginWithGoogle({
  redirectTo: '/dashboard'
})

React Component

function GoogleLoginButton() {
  const { loginWithGoogle } = useGately()

  return (
    <button onClick={() => loginWithGoogle({ redirectTo: '/dashboard' })}>
      <GoogleIcon />
      Continue with Google
    </button>
  )
}

await gately.loginWithGithub(options)

Options

Option	Type	Default	Description
`redirectTo`	string	Current URL	URL to redirect after login. Must be an allowed redirect URL

Example

// Simple usage
await gately.loginWithGithub()

// With redirect
await gately.loginWithGithub({
  redirectTo: '/dashboard'
})

React Component

function GithubLoginButton() {
  const { loginWithGithub } = useGately()

  return (
    <button onClick={() => loginWithGithub({ redirectTo: '/dashboard' })}>
      <GithubIcon />
      Continue with GitHub
    </button>
  )
}

OAuth Flow

User clicks social login button
SDK sends the user to Gately, which checks redirectTo is allowed for your project
Gately redirects to the OAuth provider (Google/GitHub)
User authorizes your application
Provider redirects back to Gately, which signs the user in
Gately redirects to redirectTo with a single-use gately_code
SDK exchanges the code for the session and the user is logged in

Configuration

Enable OAuth Providers

Go to Settings > Social Sign-On in your dashboard
Enable Google and/or GitHub
Add your OAuth credentials

Google Setup

Go to Google Cloud Console
Create a new project or select existing
Enable Google+ API
Create OAuth 2.0 credentials
Add authorized redirect URI: https://api.usegately.com/sdk/sso/google/callback
Copy Client ID and Client Secret to Gately

GitHub Setup

Go to GitHub Developer Settings
Create a new OAuth App
Set Authorization callback URL: https://api.usegately.com/api/auth/github/callback
Copy Client ID and Client Secret to Gately

If OAuth runs on your custom domain (see below), use that domain in place of api.usegately.com in both callback URLs.

Custom Domain

If you have a custom domain configured:

// SDK automatically uses your custom domain for OAuth
await gately.loginWithGoogle()
// Redirects to: https://auth.yourdomain.com/api/v1/sso/google

Handling OAuth Redirect

The SDK automatically handles OAuth redirects. When the user lands on redirectTo with a gately_code parameter, the SDK:

Removes gately_code from the address bar
Exchanges the code for the session (codes are single-use and expire after 60 seconds)
Saves the session to localStorage
Dispatches the gately:auth-success event (or gately:auth-error if the exchange fails)

Make sure the SDK is initialized on the page you redirect to.

// Listen for OAuth success
window.addEventListener('gately:auth-success', (event) => {
  const { session, user } = event.detail
  console.log('OAuth login successful:', user.email)
})

// Listen for OAuth errors
window.addEventListener('gately:auth-error', (event) => {
  const { error, message } = event.detail
  console.error('OAuth failed:', message)
})

Without the SDK

If you start OAuth yourself, add response_mode=code so Gately returns a one-time code instead of putting the session in the URL:

https://api.usegately.com/api/v1/sso/google?project_id=YOUR_PROJECT_ID&redirect_to=https%3A%2F%2Facme.com%2Faccount&response_mode=code

Then exchange the gately_code from the redirect within 60 seconds:

curl -X POST "https://api.usegately.com/api/v1/sso/exchange"   -H "Content-Type: application/json"   -d '{ "code": "GATELY_CODE", "project_id": "YOUR_PROJECT_ID" }'

{
  "session": { "access_token": "...", "expires_at": 1767225600000, "user": { ... } },
  "user": { "id": "...", "email": "user@example.com", "name": "Jane Doe" }
}

Without response_mode=code, Gately falls back to the legacy behavior of adding gately_session and gately_user to the redirect URL. This is only kept for older SDK versions; the redirect URL must still be allowed.

Error Handling

try {
  await gately.loginWithGoogle()
} catch (error) {
  // Note: Most errors occur during redirect, not here
  console.error('Failed to initiate OAuth:', error)
}

// Handle errors from redirect
window.addEventListener('gately:auth-error', (event) => {
  const { error, message } = event.detail
  
  switch (error) {
    case 'access_denied':
      showError('You cancelled the login')
      break
    case 'invalid_request':
      showError('Login configuration error')
      break
    default:
      showError('Login failed. Please try again.')
  }
})

User Data from OAuth

OAuth providers return user profile data:

Google

{
  email: 'user@gmail.com',
  full_name: 'John Doe',
  avatar_url: 'https://lh3.googleusercontent.com/...',
  metadata: {
    google_id: '123456789',
    locale: 'en'
  }
}

GitHub

{
  email: 'user@example.com',
  full_name: 'johndoe',
  avatar_url: 'https://avatars.githubusercontent.com/...',
  metadata: {
    github_id: 12345,
    github_username: 'johndoe'
  }
}

Linking Accounts

If a user signs up with email and later tries to login with OAuth using the same email, the accounts are automatically linked. Linking only happens with a verified email address: Google accounts must have a verified email, and for GitHub Gately uses the account’s primary verified email (an unverified profile email is ignored). Users without one see an error asking them to verify their email with the provider.

// User signs up with email
await gately.signup('user@example.com', 'password')

// Later, user logs in with Google (same email)
await gately.loginWithGoogle()
// Same account, now linked to Google

Getting Started

Features

Platform Guides

SDK

Authentication

Users

Campaigns

Contacts

Protection

Options

Example

React Component

Options

Example

React Component

OAuth Flow

Configuration

Enable OAuth Providers

Google Setup

GitHub Setup

Custom Domain

Handling OAuth Redirect

Without the SDK

Error Handling

User Data from OAuth

Google

GitHub

Linking Accounts

​Google Login

​Options

​Example

​React Component

​GitHub Login

​Options

​Example

​React Component

​OAuth Flow

​Configuration

​Enable OAuth Providers

​Google Setup

​GitHub Setup

​Custom Domain

​Handling OAuth Redirect

​Without the SDK

​Error Handling

​User Data from OAuth

​Google

​GitHub

​Linking Accounts

Google Login

Options

Example

React Component

GitHub Login

Options

Example

React Component

OAuth Flow

Configuration

Enable OAuth Providers

Google Setup

GitHub Setup

Custom Domain

Handling OAuth Redirect

Without the SDK

Error Handling

User Data from OAuth

Google

GitHub

Linking Accounts