React SDK

The @gately/react SDK provides production-ready authentication for React applications with a hooks-based API and automatic state management.

Version: @gately/react@2.2.0
Features: useGately hook, GatelyProvider context, TypeScript support, SSR support

Installation

npm install @gately/react@latest

Or install a specific version:

npm install @gately/react@2.2.0

Get your API key: Dashboard → Settings → API Keys

Quick Start

import { GatelyProvider, useGately } from '@gately/react'

function App() {
  return (
    <GatelyProvider apiKey={process.env.REACT_APP_GATELY_API_KEY}>
      <Dashboard />
    </GatelyProvider>
  )
}

function Dashboard() {
  const { user, isAuthenticated, logout } = useGately()

  if (!isAuthenticated) return <LoginForm />

  return (
    <div>
      <h1>Welcome, {user?.email}!</h1>
      <button onClick={logout}>Logout</button>
    </div>
  )
}

GatelyProvider

Wraps your app to provide authentication context. Must be a parent of any component using useGately.

import { GatelyProvider } from '@gately/react'

<GatelyProvider
  apiKey={process.env.REACT_APP_GATELY_API_KEY}
  apiUrl="https://api.usegately.com"   // optional
  autoRefresh={true}                    // optional, default: true
>
  <App />
</GatelyProvider>

Prop	Type	Required	Description
`apiKey`	`string`	✅	Your Gately API key
`apiUrl`	`string`	No	Custom API URL
`autoRefresh`	`boolean`	No	Auto-refresh sessions (default: `true`)

useGately Hook

The main hook — provides all auth state and methods.

const {
  // State
  user,
  session,
  isAuthenticated,
  isLoading,
  error,

  // Auth methods
  login,
  signup,
  logout,
  sendMagicLink,
  resetPassword,

  // User methods
  getUserProfile,
  updateUserProfile,
  changePassword,
  deleteUserAccount,

  // Session
  fetchSession,
  client
} = useGately()

State

Property	Type	Description
`user`	`User \| null`	Currently authenticated user
`session`	`Session \| null`	Current session
`isAuthenticated`	`boolean`	Whether user is logged in
`isLoading`	`boolean`	Loading state for auth operations
`error`	`Error \| null`	Error from last operation

Methods

Method	Signature	Description
`login`	`(email, password) => Promise`	Login with email/password
`signup`	`(email, password, metadata?) => Promise`	Create a new account
`logout`	`() => Promise<void>`	End current session
`sendMagicLink`	`(email, redirectTo?) => Promise<void>`	Send passwordless link
`resetPassword`	`(email) => Promise<void>`	Send password reset email
`getUserProfile`	`() => Promise`	Fetch full user profile
`updateUserProfile`	`(updates) => Promise`	Update user profile
`changePassword`	`(current, new) => Promise<void>`	Change password
`deleteUserAccount`	`() => Promise<void>`	Delete account
`fetchSession`	`() => Promise<Session \| null>`	Refresh session from server

Authentication Examples

import { useGately } from '@gately/react'
import { useState } from 'react'

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

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()
    try {
      await login(email, password)
      // redirect or update UI
    } catch (err) {
      // error is also available via the hook's error property
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" value={email} onChange={e => setEmail(e.target.value)} />
      <input type="password" value={password} onChange={e => setPassword(e.target.value)} />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Signing in...' : 'Sign In'}
      </button>
      {error && <p className="error">{error.message}</p>}
    </form>
  )
}

function SignupForm() {
  const { signup, isLoading, error } = useGately()

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()
    await signup(email, password, { name: 'Jane Doe' })
  }

  // ...
}

Magic Link

function MagicLinkForm() {
  const { sendMagicLink, isLoading } = useGately()
  const [sent, setSent] = useState(false)

  const handleSend = async (email: string) => {
    await sendMagicLink(email)
    setSent(true)
  }

  return sent
    ? <p>Check your email!</p>
    : <button onClick={() => handleSend('user@example.com')} disabled={isLoading}>
        Send Magic Link
      </button>
}

Route Protection

With React Router

import { useGately } from '@gately/react'
import { Navigate } from 'react-router-dom'

function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { isAuthenticated, isLoading } = useGately()

  if (isLoading) return <div>Loading...</div>
  if (!isAuthenticated) return <Navigate to="/login" replace />

  return <>{children}</>
}

// Usage
<Routes>
  <Route path="/login" element={<LoginPage />} />
  <Route
    path="/dashboard"
    element={
      <ProtectedRoute>
        <Dashboard />
      </ProtectedRoute>
    }
  />
</Routes>

User Profile

function ProfilePage() {
  const { user, updateUserProfile, isLoading } = useGately()
  const [name, setName] = useState(user?.name ?? '')

  const handleSave = async () => {
    await updateUserProfile({ name })
  }

  return (
    <div>
      <p>{user?.email}</p>
      <input value={name} onChange={e => setName(e.target.value)} />
      <button onClick={handleSave} disabled={isLoading}>Save</button>
    </div>
  )
}

Other Hooks

useAuth

Returns the full auth context (same as useGately):

import { useAuth } from '@gately/react'

const { login, logout, isAuthenticated } = useAuth()

useUser

Focused hook for user profile data:

import { useUser } from '@gately/react'

const { user, profile, isLoading, refetch, update } = useUser()

useProtected

Simple auth status check:

import { useProtected } from '@gately/react'

const { isAuthenticated, isLoading, user } = useProtected()

TypeScript

import type { User, Session, GatelyContextValue } from '@gately/react'

const handleUser = (user: User) => {
  console.log(user.id, user.email, user.name)
}

Testing

jest.mock('@gately/react', () => ({
  ...jest.requireActual('@gately/react'),
  useGately: () => ({
    user: { id: '1', email: 'test@example.com' },
    isAuthenticated: true,
    isLoading: false,
    error: null,
    logout: jest.fn()
  })
}))

Next Steps

Next.js SDK

Add server-side auth and middleware

Node.js SDK

Backend token verification

Support: support@usegately.com · Slack Community

Getting Started

Features

Platform Guides

SDK

Authentication

Users

Campaigns

Contacts

Protection

Installation

Quick Start

GatelyProvider

useGately Hook

State

Methods

Authentication Examples

Magic Link

Route Protection

With React Router

User Profile

Other Hooks

useAuth

useUser

useProtected

TypeScript

Testing

Next Steps

Next.js SDK

Node.js SDK

​Installation

​Quick Start

​GatelyProvider

​useGately Hook

​State

​Methods

​Authentication Examples

​Login Form

​Sign Up

​Magic Link

​Route Protection

​With React Router

​User Profile

​Other Hooks

​useAuth

​useUser

​useProtected

​TypeScript

​Testing

​Next Steps

Next.js SDK

Node.js SDK

Installation

Quick Start

GatelyProvider

useGately Hook

State

Methods

Authentication Examples

Login Form

Sign Up

Magic Link

Route Protection

With React Router

User Profile

Other Hooks

useAuth

useUser

useProtected

TypeScript

Testing

Next Steps