> ## 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.

# Social Login

> Authenticate users with Google and GitHub

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

## Google Login

```javascript theme={null}
await gately.loginWithGoogle(options)
```

### Options

| Option       | Type   | Default     | Description                 |
| ------------ | ------ | ----------- | --------------------------- |
| `redirectTo` | string | Current URL | URL to redirect after login |

### Example

```javascript theme={null}
// Simple usage
await gately.loginWithGoogle()

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

### React Component

```jsx theme={null}
function GoogleLoginButton() {
  const { loginWithGoogle } = useGately()

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

## GitHub Login

```javascript theme={null}
await gately.loginWithGithub(options)
```

### Options

| Option       | Type   | Default     | Description                 |
| ------------ | ------ | ----------- | --------------------------- |
| `redirectTo` | string | Current URL | URL to redirect after login |

### Example

```javascript theme={null}
// Simple usage
await gately.loginWithGithub()

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

### React Component

```jsx theme={null}
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

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Your App
    participant Gately
    participant OAuth Provider
    
    User->>Your App: Click "Login with Google"
    Your App->>Gately: loginWithGoogle()
    Gately->>OAuth Provider: Redirect to authorize
    OAuth Provider->>User: Show consent screen
    User->>OAuth Provider: Approve
    OAuth Provider->>Gately: Redirect with code
    Gately->>OAuth Provider: Exchange code for token
    OAuth Provider->>Gately: Return user info
    Gately->>Your App: Redirect with session
    Your App->>User: Logged in!
```

## 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](https://console.cloud.google.com)
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](https://github.com/settings/developers)
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:

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
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

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

### GitHub

```javascript theme={null}
{
  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.

```javascript theme={null}
// 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
```