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

# Authentication

> Learn about authentication methods in Gately

Gately supports multiple authentication methods to fit your application's needs.

## Authentication Methods

<CardGroup cols={2}>
  <Card title="Email & Password" icon="envelope">
    Traditional email and password authentication with secure password hashing.
  </Card>

  <Card title="Social Login" icon="share-nodes">
    One-click login with Google and GitHub OAuth providers.
  </Card>

  <Card title="Magic Links" icon="wand-magic-sparkles">
    Passwordless authentication via email links.
  </Card>

  <Card title="API Keys" icon="key">
    Server-to-server authentication for backend integrations.
  </Card>
</CardGroup>

## Email & Password

The most common authentication method. Users register with their email and a secure password.

### Password Requirements

* Minimum 8 characters
* At least one uppercase letter
* At least one lowercase letter
* At least one number

```javascript theme={null}
// Sign up
const { user } = await gately.signup('user@example.com', 'SecurePass123!', {
  full_name: 'John Doe'
})

// Login
const { user, session } = await gately.login('user@example.com', 'SecurePass123!')
```

## Social Login

Enable users to sign in with their existing Google or GitHub accounts.

### Google Login

```javascript theme={null}
await gately.loginWithGoogle({
  redirectTo: '/dashboard'
})
```

### GitHub Login

```javascript theme={null}
await gately.loginWithGithub({
  redirectTo: '/dashboard'
})
```

<Note>
  Social login providers must be configured in your project settings before use.
</Note>

### Configuring OAuth Providers

1. Go to **Settings > Authentication** in your dashboard
2. Enable the desired provider (Google or GitHub)
3. Add your OAuth credentials:
   * **Google**: Client ID and Client Secret from Google Cloud Console
   * **GitHub**: Client ID and Client Secret from GitHub Developer Settings

## Magic Links

Passwordless authentication sends a secure link to the user's email.

```javascript theme={null}
// Send magic link
await gately.sendMagicLink('user@example.com', {
  redirectTo: '/dashboard'
})
```

The user clicks the link in their email and is automatically logged in.

## Session Management

### Check Authentication Status

```javascript theme={null}
if (gately.isAuthenticated()) {
  const user = gately.getUser()
  const session = gately.getSession()
  
  console.log('User:', user.email)
  console.log('Session expires:', new Date(session.expires_at))
}
```

### Listen for Auth Changes

```javascript theme={null}
gately.onAuthStateChange((user, session) => {
  if (user) {
    console.log('User logged in:', user.email)
  } else {
    console.log('User logged out')
  }
})
```

### Refresh Session

Sessions are automatically refreshed before expiry. You can also manually refresh:

```javascript theme={null}
const session = await gately.fetchSession()
```

### Logout

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

## Password Reset

### Request Reset

```javascript theme={null}
await gately.requestPasswordReset('user@example.com')
// User receives email with reset link
```

### Confirm Reset

```javascript theme={null}
await gately.confirmPasswordReset(
  'user@example.com',
  'reset-token-from-email',
  'NewSecurePass123!'
)
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use HTTPS">
    Always serve your application over HTTPS to protect authentication tokens in transit.
  </Accordion>

  <Accordion title="Secure Password Storage">
    Gately uses bcrypt with salt rounds for secure password hashing. Never store plain-text passwords.
  </Accordion>

  <Accordion title="Token Expiry">
    Access tokens expire after 1 hour by default. Refresh tokens are valid for 7 days.
  </Accordion>

  <Accordion title="Rate Limiting">
    Authentication endpoints are rate-limited to prevent brute force attacks.
  </Accordion>
</AccordionGroup>