Complete reference for authentication methods and OAuth integration.
GatelyBrowserClient
The main client class for browser environments with OAuth and UI control support.
Constructor
new GatelyBrowserClient(projectId: string, options?: GatelyOptions)
Your Gately project ID (UUID format)
Configuration options for the client
GatelyOptions
apiUrl
string
default:"https://sdk.usegately.com"
Custom API URL for the Gately service
Automatically refresh tokens when they expire
Authentication Methods
login()
Sign in with email and password.
login(email: string, password: string): Promise<AuthResponse>
try {
const response = await gately.login('user@example.com', 'password123')
console.log('Login successful:', response.user)
} catch (error) {
console.error('Login failed:', error.message)
}
Promise<AuthResponse>
signup()
Create a new user account.
signup(email: string, password: string, metadata?: SignupMetadata): Promise<AuthResponse>
User’s password (minimum 8 characters)
try {
const response = await gately.signup('user@example.com', 'password123', {
tier: 'basic',
role: 'user',
name: 'John Doe'
})
console.log('Signup successful:', response.user)
} catch (error) {
console.error('Signup failed:', error.message)
}
Promise<AuthResponse>
logout()
Sign out the current user.
Example:
try {
await gately.logout()
console.log('Logout successful')
} catch (error) {
console.error('Logout failed:', error.message)
}
Promise<void>
sendMagicLink()
Send passwordless login link via email.
sendMagicLink(email: string, options?: LoginOptions): Promise<void>
Additional options for the magic link
try {
await gately.sendMagicLink('user@example.com', {
redirectTo: 'https://yourapp.com/dashboard'
})
console.log('Magic link sent successfully')
} catch (error) {
console.error('Failed to send magic link:', error.message)
}
Promise<void>
resetPassword()
Send password reset email.
resetPassword(email: string): Promise<void>
try {
await gately.resetPassword('user@example.com')
console.log('Password reset email sent')
} catch (error) {
console.error('Failed to send reset email:', error.message)
}
Promise<void>
OAuth Methods
loginWithGoogle()
Sign in with Google OAuth.
loginWithGoogle(options?: SSOOptions): Promise<void>
OAuth configuration options
// Popup mode (default)
await gately.loginWithGoogle()
// Redirect mode
await gately.loginWithGoogle({
mode: 'redirect',
redirectUrl: 'https://yourapp.com/dashboard'
})
// Custom popup options
await gately.loginWithGoogle({
mode: 'popup',
popupOptions: {
width: 600,
height: 700
}
})
Promise<void>
loginWithGithubSSO()
Sign in with GitHub OAuth.
loginWithGithubSSO(options?: SSOOptions): Promise<void>
OAuth configuration options
// Popup mode
await gately.loginWithGithubSSO({
mode: 'popup',
popupOptions: {
width: 500,
height: 600
}
})
// Redirect mode
await gately.loginWithGithubSSO({
mode: 'redirect',
redirectUrl: window.location.href
})
Promise<void>
State Management Methods
isAuthenticated()
Check if user is currently authenticated.
isAuthenticated(): boolean
if (gately.isAuthenticated()) {
console.log('User is logged in')
} else {
console.log('User is not logged in')
}
boolean
getUser()
Get current authenticated user.
Example:
const user = gately.getUser()
if (user) {
console.log('Current user:', user.email)
console.log('User ID:', user.id)
console.log('Created at:', user.created_at)
}
User | null
getSession()
Get current user session.
getSession(): Session | null
const session = gately.getSession()
if (session) {
console.log('Access token:', session.access_token)
console.log('Expires at:', new Date(session.expires_at))
}
Session | null
onAuthStateChange()
Listen for authentication state changes.
onAuthStateChange(callback: (user: User | null, session: Session | null) => void): () => void
Function called when auth state changes
const unsubscribe = gately.onAuthStateChange((user, session) => {
if (user) {
console.log('User logged in:', user.email)
} else {
console.log('User logged out')
}
})
// Remove listener when done
unsubscribe()
() => void (unsubscribe function)
React Hook
useGately()
React hook for reactive authentication state.
useGately(projectId: string, options?: GatelyOptions): UseGatelyReturn
import { useGately } from 'https://cdn.usegately.com/gately-sdk.esm.min.js'
function App() {
const {
user,
session,
loading,
error,
login,
logout,
signup
} = useGately('your-project-id')
if (loading) return <div>Loading...</div>
return (
<div>
{user ? (
<div>
<h1>Welcome, {user.email}!</h1>
<button onClick={logout}>Logout</button>
</div>
) : (
<button onClick={() => login('email', 'password')}>
Login
</button>
)}
</div>
)
}
UseGatelyReturn
Current authenticated user
Loading state for authentication operations
Error message from last operation
Login with email and password
Send passwordless login link
Send password reset email
Direct access to the SDK client
Type Definitions
AuthResponse
interface AuthResponse {
user: User
session: Session
project_id?: string
}
interface SignupMetadata {
tier?: string
role?: string
name?: string
[key: string]: any
}
LoginOptions
interface LoginOptions {
redirectTo?: string
}
SSOOptions
interface SSOOptions {
mode?: 'popup' | 'redirect'
redirectUrl?: string
popupOptions?: {
width?: number
height?: number
scrollbars?: boolean
resizable?: boolean
}
}
Error Handling
All authentication methods can throw errors with the following structure:
interface GatelyError extends Error {
code: string
status?: number
details?: any
}
Common Error Codes
Wrong email/password combination
User doesn’t exist in the system
Email address not verified
Too many authentication attempts
Connection or network issues
Invalid or missing project ID
Next Steps
