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

# Login

> Authenticate users with email and password

## Basic Login

```javascript theme={null}
const { user, session } = await gately.login(email, password)
```

### Parameters

| Parameter  | Type   | Required | Description          |
| ---------- | ------ | -------- | -------------------- |
| `email`    | string | Yes      | User's email address |
| `password` | string | Yes      | User's password      |

### Response

```typescript theme={null}
interface AuthResponse {
  user: User
  session: Session
}

interface User {
  id: string
  email: string
  full_name: string | null
  avatar_url: string | null
  plan_id: string
  status: string
  metadata: Record<string, any>
  created_at: string
}

interface Session {
  access_token: string
  refresh_token: string
  expires_at: number
  user: User
}
```

## Example

```javascript theme={null}
import { GatelyClient } from '@gately/sdk'

const gately = new GatelyClient('YOUR_PROJECT_ID')

async function handleLogin(email, password) {
  try {
    const { user, session } = await gately.login(email, password)
    
    console.log('Logged in as:', user.email)
    console.log('Session expires:', new Date(session.expires_at))
    
    // Redirect to dashboard
    window.location.href = '/dashboard'
  } catch (error) {
    console.error('Login failed:', error.message)
    // Handle error (show message to user)
  }
}
```

## React Hook

```jsx theme={null}
import { useGately } from '@gately/sdk'

function LoginForm() {
  const { login } = useGately()
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  const [error, setError] = useState('')

  const handleSubmit = async (e) => {
    e.preventDefault()
    try {
      await login(email, password)
      // Redirect handled automatically or manually
    } catch (err) {
      setError(err.message)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {error && <p className="error">{error}</p>}
      <input 
        type="email" 
        value={email} 
        onChange={(e) => setEmail(e.target.value)} 
        placeholder="Email"
      />
      <input 
        type="password" 
        value={password} 
        onChange={(e) => setPassword(e.target.value)} 
        placeholder="Password"
      />
      <button type="submit">Log In</button>
    </form>
  )
}
```

## Error Handling

Common errors:

| Error                  | Description                         |
| ---------------------- | ----------------------------------- |
| `Invalid email format` | Email doesn't match expected format |
| `Password is required` | Password field is empty             |
| `Invalid credentials`  | Email or password is incorrect      |
| `Account not found`    | No account with this email          |
| `Account disabled`     | Account has been deactivated        |

```javascript theme={null}
try {
  await gately.login(email, password)
} catch (error) {
  switch (error.code) {
    case 'INVALID_CREDENTIALS':
      showError('Invalid email or password')
      break
    case 'ACCOUNT_DISABLED':
      showError('Your account has been disabled')
      break
    default:
      showError('Login failed. Please try again.')
  }
}
```

## Session Management

After login, the session is automatically:

* Stored in localStorage
* Set as cookies for cross-origin requests
* Refreshed before expiry (if `autoRefresh` is enabled)

```javascript theme={null}
// Check if logged in
if (gately.isAuthenticated()) {
  const user = gately.getUser()
  const session = gately.getSession()
}

// Listen for auth changes
gately.onAuthStateChange((user, session) => {
  if (user) {
    console.log('User logged in:', user.email)
  } else {
    console.log('User logged out')
  }
})
```

## Redirect After Login

Configure automatic redirects:

```javascript theme={null}
// In project settings or via SDK
await gately.login(email, password)
// SDK checks redirect rules and redirects automatically
```

Or handle manually:

```javascript theme={null}
const { user } = await gately.login(email, password)

// Redirect based on plan
if (user.plan_id === 'pro') {
  window.location.href = '/pro-dashboard'
} else {
  window.location.href = '/dashboard'
}
```