Auth Module

The Auth module handles all authentication flows for both storefront customers and admin users. It integrates with hanzo.id for OAuth2 and supports email/password, token refresh, and session management.

Setup

import { HanzoSDK } from '@hanzo/sdk'

const sdk = new HanzoSDK({
  baseUrl: 'https://api.hanzo.ai/v1',
  apiKey: 'your-api-key',
})

Email / Password Authentication

const session = await sdk.auth.login({
  email: '[email protected]',
  password: 'their-password',
})

console.log(session.accessToken)  // JWT access token
console.log(session.refreshToken) // Refresh token for renewal
console.log(session.expiresAt)    // Token expiry timestamp

Register

const session = await sdk.auth.register({
  email: '[email protected]',
  password: 'secure-password',
  firstName: 'Jane',
  lastName: 'Doe',
})

Registration returns a session immediately -- the user is logged in after creation.

Logout

await sdk.auth.logout()

This invalidates the current session on the server and clears local token state.

Token Management

Refresh Tokens

Access tokens expire after a configurable period (default: 1 hour). Use the refresh token to obtain a new access token without requiring the user to log in again:

const newSession = await sdk.auth.refresh()
console.log(newSession.accessToken)

The SDK can handle token refresh automatically when configured:

const sdk = new HanzoSDK({
  baseUrl: 'https://api.hanzo.ai/v1',
  apiKey: 'your-api-key',
  autoRefresh: true, // Automatically refresh expired tokens
})

Get Current User

Retrieve the authenticated user's profile:

const user = await sdk.auth.me()

console.log(user.id)        // "cust_abc123"
console.log(user.email)     // "[email protected]"
console.log(user.firstName) // "Jane"
console.log(user.lastName)  // "Doe"
console.log(user.role)      // "customer" | "admin"

Update Profile

await sdk.auth.updateProfile({
  firstName: 'Jane',
  lastName: 'Smith',
  phone: '+1-555-0123',
})

Change Password

await sdk.auth.changePassword({
  currentPassword: 'old-password',
  newPassword: 'new-secure-password',
})

Password Reset

Request Reset

await sdk.auth.requestPasswordReset({
  email: '[email protected]',
})
// Sends a reset email with a one-time token

Complete Reset

await sdk.auth.resetPassword({
  token: 'reset-token-from-email',
  newPassword: 'new-secure-password',
})

The SDK supports OAuth2 flows through hanzo.id providers:

Initiate OAuth Flow

// Redirect the user to the OAuth provider
const authUrl = sdk.auth.getOAuthUrl({
  provider: 'google',    // 'google' | 'github' | 'apple' | 'discord'
  redirectUri: 'https://yourstore.com/auth/callback',
  scopes: ['openid', 'email', 'profile'],
})

window.location.href = authUrl

Handle Callback

// In your callback route handler
const session = await sdk.auth.handleOAuthCallback({
  provider: 'google',
  code: urlParams.get('code'),
  redirectUri: 'https://yourstore.com/auth/callback',
})

Supported Providers

Provider	Identifier	Scopes
Google	`google`	`openid`, `email`, `profile`
GitHub	`github`	`user:email`, `read:user`
Apple	`apple`	`email`, `name`
Discord	`discord`	`identify`, `email`

Session Storage

By default, the SDK stores tokens in memory. Configure a custom storage backend for persistence:

const sdk = new HanzoSDK({
  baseUrl: 'https://api.hanzo.ai/v1',
  apiKey: 'your-api-key',
  storage: {
    get: (key: string) => localStorage.getItem(key),
    set: (key: string, value: string) => localStorage.setItem(key, value),
    remove: (key: string) => localStorage.removeItem(key),
  },
})

Never store tokens in localStorage for applications that handle sensitive data. Use httpOnly cookies or in-memory storage with token refresh instead.

Admin Authentication

Admin users authenticate through the same module but require admin role credentials:

const session = await sdk.auth.login({
  email: '[email protected]',
  password: 'admin-password',
})

// Verify the user has admin access
const user = await sdk.auth.me()
if (user.role !== 'admin') {
  throw new Error('Insufficient permissions')
}

For the admin dashboard, see the Admin Setup Guide for PKCE-based OAuth configuration.

On this page