FeaturesAuthenticationOverview

Authentication

Aerostack Auth is a complete, production-ready authentication system. It handles user registration, login, OTP codes, email verification, and password resets — out of the box, with zero configuration required.

What’s included

  • Email + password registration and login
  • OTP / Magic Link — passwordless sign-in via 6-digit codes
  • Email verification — confirm email on sign-up
  • Password reset — secure token-based reset flow
  • Session management — access tokens + refresh token rotation
  • Profile management — update name, avatar, custom fields
  • Rate limiting — brute-force protection built in
  • Cloudflare Turnstile — optional bot protection on any endpoint

Quick start

1. Install the SDK

npm install @aerostack/react

2. Wrap your app

// app.tsx
import { AerostackProvider } from '@aerostack/react'
 
export default function App() {
  return (
    <AerostackProvider
      projectId="your-project-id"
      apiKey="your-api-key"
      baseUrl="https://api.aerostack.dev/v1"
    >
      <YourApp />
    </AerostackProvider>
  )
}

3. Use auth in any component

import { useAuth } from '@aerostack/react'
 
export function LoginForm() {
  const { signIn, user, loading, error } = useAuth()
 
  const handleSubmit = async (e) => {
    e.preventDefault()
    await signIn(email, password)
  }
 
  if (user) return <p>Welcome, {user.name}!</p>
 
  return (
    <form onSubmit={handleSubmit}>
      <input type="email" onChange={e => setEmail(e.target.value)} />
      <input type="password" onChange={e => setPassword(e.target.value)} />
      {error && <p className="text-red-500">{error}</p>}
      <button type="submit" disabled={loading}>
        {loading ? 'Signing in...' : 'Sign in'}
      </button>
    </form>
  )
}

Auth state

The useAuth hook returns the full auth state:

const {
  user,            // User | null — current user object
  tokens,          // { accessToken, refreshToken, expiresAt } | null
  loading,         // boolean — any auth operation in progress
  error,           // string | null — last error message
  isAuthenticated, // boolean — shorthand for !!tokens?.accessToken
} = useAuth()

The user object shape:

interface User {
  id: string
  email: string
  name?: string
  avatar_url?: string
  emailVerified: boolean
  createdAt?: string
  customFields?: Record<string, any>
}

Use Cases

SaaS multi-tenant authentication

Build a B2B SaaS where each customer organization has isolated user pools. Aerostack projects map 1:1 to tenants, so each tenant gets its own auth configuration, rate limits, and user database. Users sign up under their organization’s project, and JWT tokens are scoped to that tenant automatically.

Mobile OTP login

Let users sign in with a 6-digit code sent to their email — no password to remember. This is ideal for mobile apps where typing passwords is friction. Call sdk.auth.requestOtp(email), show a code input, then verify with sdk.auth.verifyOtp(email, code). The entire flow is two API calls.

// Request OTP
await sdk.auth.requestOtp({ email: 'user@example.com' })
 
// User enters the 6-digit code from their email
const { user, tokens } = await sdk.auth.verifyOtp({
  email: 'user@example.com',
  code: '482901',
})

Email verification on sign-up

Require users to confirm their email before accessing your app. Enable email verification in Dashboard, and Aerostack automatically sends a verification email on registration. Your app checks user.emailVerified to gate access to protected pages.

Passwordless magic links

Send a one-click login link via email instead of asking for a password. This works well for low-frequency apps like monthly reports or admin panels where users do not want to manage yet another password.

Bot protection with Turnstile

Add Cloudflare Turnstile to your login and registration forms to block credential-stuffing attacks without annoying users with CAPTCHAs. Pass the turnstileToken parameter alongside any auth call, and Aerostack validates it server-side before processing the request.

Next steps

OverviewRegistration & Login