Skip to main content
The Gately SDK handles session management automatically, including storage, refresh, and state synchronization.

Check Authentication

Get Current User

User Object

Get Session

Session Object

Listen for Auth Changes

React Hook

Refresh Session

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

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

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:
The SDK refreshes the session 5 minutes before expiry. To disable:

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:

Server-Side Rendering

For SSR frameworks (Next.js, etc.):

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:
This logs:
  • Session save/restore operations
  • Token refresh attempts
  • Auth state changes