JavaScript SDK

Universal JavaScript client for ezAuth. Zero dependencies. Works in Node.js 18+ and all modern browsers.

Installation

npm install @ezauth/client

Available as ESM, CJS, and IIFE (browser global) builds:

Initialization

import { EZAuth } from '@ezauth/client'

// Frontend (publishable key)
const ez = new EZAuth({
  baseUrl: 'https://auth.example.com',
  publishableKey: 'pk_live_...',
})

// Backend (secret key)
const ez = new EZAuth({
  baseUrl: 'https://auth.example.com',
  secretKey: 'sk_live_...',
})

Error Handling

All methods throw EZAuthError on failure:

import { EZAuth, EZAuthError } from '@ezauth/client'

try {
  await ez.users.get('nonexistent')
} catch (err) {
  if (err instanceof EZAuthError) {
    console.log(err.message)  // "User not found"
    console.log(err.status)   // 404
  }
}

ez.auth (Publishable Key)

Frontend authentication operations.

signUp(options)

Create a new user account. Sends a verification email.

await ez.auth.signUp({
  email: '[email protected]',
  password: 's3cret',          // optional
  redirectUrl: 'https://...',  // optional, for magic link redirect
})

signIn(options)

Sign in a user. Strategy is auto-detected from the presence of password.

// Password sign-in (returns session immediately)
const session = await ez.auth.signIn({
  email: '[email protected]',
  password: 's3cret',
})

// Magic link (sends email, no immediate session)
await ez.auth.signIn({
  email: '[email protected]',
  redirectUrl: 'https://myapp.com/dashboard',
})

verifyCode(options)

Verify a 6-digit code from email. Returns a session.

const session = await ez.auth.verifyCode({
  email: '[email protected]',
  code: '482917',
})
// session.access_token, session.refresh_token, session.user_id, session.session_id

getSession()

Get the current authenticated user's information.

const me = await ez.auth.getSession()
// { user_id, email, email_verified, is_bot }

signOut()

Sign out the current session.

await ez.auth.signOut()

refreshToken(refreshToken)

Exchange a refresh token for a new access/refresh token pair.

const newSession = await ez.auth.refreshToken('rt_...')

ssoExchange(token)

Exchange an SSO token for a session (for cross-domain SSO).

const session = await ez.auth.ssoExchange(ssoToken)

signInWithOAuth(options)

Get an OAuth authorization URL to redirect the user.

const { authorization_url } = await ez.auth.signInWithOAuth({
  provider: 'google',
  redirectUrl: 'https://myapp.com/dashboard',
})
window.location.href = authorization_url

requestChallenge()

Request a hashcash proof-of-work challenge (for signup when hashcash is enabled).

const challenge = await ez.auth.requestChallenge()
// { challenge, difficulty, algorithm, params, expires_in }

ez.users (Secret Key)

Backend user management.

users.list(options?)

const { users, total } = await ez.users.list({
  limit: 10,    // default: 50
  offset: 0,
  email: '[email protected]',  // optional filter
})

users.create(options)

const user = await ez.users.create({
  email: '[email protected]',
  password: 'optional',
})

users.get(userId)

const user = await ez.users.get('user-uuid')

ez.sessions (Secret Key)

sessions.revoke(sessionId)

await ez.sessions.revoke('session-uuid')

sessions.createSignInToken(options)

const result = await ez.sessions.createSignInToken({
  userId: 'user-uuid',
  expiresInSeconds: 300,  // default: 300
})
// result.token, result.refresh_token, result.expires_at

ez.tables (Secret Key)

Custom table management. See Custom Tables for concepts.

tables.create(options)

const table = await ez.tables.create({
  name: 'contacts',
  columns: [
    { name: 'name', type: 'text', required: true },
    { name: 'age', type: 'int' },
  ],
})

tables.list()

const { tables, total } = await ez.tables.list()

tables.get(tableId)

const table = await ez.tables.get('table-uuid')
// table.columns — array of column definitions

tables.delete(tableId)

await ez.tables.delete('table-uuid')

tables.columns.add(tableId, options)

const col = await ez.tables.columns.add('table-uuid', {
  name: 'email',
  type: 'text',
  required: true,
})

tables.columns.update(tableId, columnId, options)

await ez.tables.columns.update('table-uuid', 'col-uuid', {
  name: 'full_name',
})

tables.columns.delete(tableId, columnId)

await ez.tables.columns.delete('table-uuid', 'col-uuid')

tables.rows.insert(tableId, options)

const row = await ez.tables.rows.insert('table-uuid', {
  data: { name: 'Alice', age: 30 },
})

tables.rows.get(tableId, rowId)

const row = await ez.tables.rows.get('table-uuid', 'row-uuid')

tables.rows.update(tableId, rowId, options)

await ez.tables.rows.update('table-uuid', 'row-uuid', {
  data: { age: 31 },
})

tables.rows.delete(tableId, rowId)

await ez.tables.rows.delete('table-uuid', 'row-uuid')

tables.rows.query(tableId, options?)

const { rows, next_cursor } = await ez.tables.rows.query('table-uuid', {
  filter: { field: 'age', op: 'gte', value: 18 },
  sort: { field: 'name', dir: 'asc' },
  limit: 50,
  cursor: null,
})

ez.storage (Secret Key)

storage.get()

const usage = await ez.storage.get()
// { used_bytes, limit_bytes, used_percent }