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.

The Gately SDK handles session management automatically, including storage, refresh, and state synchronization.

​
Check Authentication

// Check if user is logged in
if (gately.isAuthenticated()) {
  console.log('User is logged in')
}

​
Get Current User

const user = gately.getUser()

if (user) {
  console.log('Email:', user.email)
  console.log('Name:', user.full_name)
  console.log('Plan:', user.plan_id)
}

​
User Object

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

​
Get Session

const session = gately.getSession()

if (session) {
  console.log('Access token:', session.access_token)
  console.log('Expires at:', new Date(session.expires_at))
}

​
Session Object

interface Session {
  access_token: string
  refresh_token: string
  expires_at: number  // Unix timestamp in milliseconds
  user: User
}

​
Listen for Auth Changes

gately.onAuthStateChange((user, session) => {
  if (user) {
    console.log('User logged in:', user.email)
    // Update UI, redirect, etc.
  } else {
    console.log('User logged out')
    // Clear UI, redirect to login, etc.
  }
})

​
React Hook

import { useAuth } from '@gately/sdk'

function AuthStatus() {
  const { user, isAuthenticated, isLoading } = useAuth()

  if (isLoading) {
    return <Spinner />
  }

  if (!isAuthenticated) {
    return <Link to="/login">Log In</Link>
  }

  return <span>Welcome, {user.email}</span>
}

​
Refresh Session

Sessions are automatically refreshed before expiry. You can also manually refresh: 
const session = await gately.fetchSession()

if (session) {
  console.log('Session refreshed')
} else {
  console.log('Session expired, user logged out')
}

​
Session Storage

Sessions are stored in:
  1. localStorage: gately_session_{projectId}
  2. Cookies: gately_auth_token, gately_project_id

​
Why Both?

  • localStorage: Primary storage, survives page reloads
  • Cookies: Enables cross-origin requests (e.g., Framer fetch)

​
Session Expiry

TokenExpiry
Access Token1 hour
Refresh Token7 days
When the access token expires:
  1. SDK automatically uses refresh token
  2. New access token is obtained
  3. Session is updated in storage
When the refresh token expires:
  1. User is logged out
  2. Session is cleared
  3. Auth state callbacks are triggered

​
Auto Refresh

Auto refresh is enabled by default: 
const gately = new GatelyClient('project-id', {
  autoRefresh: true  // Default
})
The SDK refreshes the session 5 minutes before expiry. To disable: 
const gately = new GatelyClient('project-id', {
  autoRefresh: false
})

​
Logout

await gately.logout()
This will:
  1. Call the logout API endpoint
  2. Clear localStorage
  3. Clear cookies
  4. Trigger auth state callbacks
  5. Handle redirect (if configured)

​
Session Persistence

Sessions persist across:
  • Page reloads
  • Browser tabs (same origin)
  • Browser restarts (until expiry)
Sessions do NOT persist across:
  • Different browsers
  • Incognito/private mode
  • Cleared browser data

​
Multiple Tabs

The SDK handles multiple tabs gracefully: 
// Tab 1: User logs out
await gately.logout()

// Tab 2: Detects logout via storage event
// Auth state callback is triggered

​
Server-Side Rendering

For SSR frameworks (Next.js, etc.): 
// Check if running in browser
if (typeof window !== 'undefined') {
  const user = gately.getUser()
}

// Or use the hook (handles SSR automatically)
const { user, isLoading } = useAuth()

​
Security Considerations

Tokens are stored in localStorage and cookies. For high-security applications, consider additional measures like HTTP-only cookies (requires server-side setup).
Never expose tokens in URLs or log them to console in production.
The SDK uses SameSite cookies and validates the origin of requests.

​
Debugging

Enable debug mode to see session operations: 
// In browser console
localStorage.setItem('gately_debug', 'true')
location.reload()
This logs:
  • Session save/restore operations
  • Token refresh attempts
  • Auth state changes