Skip to main content

Documentation Index

Fetch the complete documentation index at: https://usegately.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Google Login

await gately.loginWithGoogle(options)

​
Options

OptionTypeDefaultDescription
redirectTostringCurrent URLURL to redirect after login

​
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>
  )
}

​
GitHub Login

await gately.loginWithGithub(options)

​
Options

OptionTypeDefaultDescription
redirectTostringCurrent URLURL to redirect after login

​
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

  1. User clicks social login button
  2. SDK redirects to OAuth provider (Google/GitHub)
  3. User authorizes your application
  4. Provider redirects back with auth code
  5. SDK exchanges code for session
  6. User is logged in and redirected

​
Configuration

​
Enable OAuth Providers

  1. Go to Settings > Authentication in your dashboard
  2. Enable Google and/or GitHub
  3. Add your OAuth credentials

​
Google Setup

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

​
GitHub Setup

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

​
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/sso/google

​
Handling OAuth Redirect

The SDK automatically handles OAuth redirects. After successful authentication:
  1. Session is saved to localStorage
  2. Cookies are set for cross-origin requests
  3. gately:auth-success event is dispatched
  4. User is redirected to redirectTo URL
// 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)
})

​
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. 
// 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