Authentication SDK Reference

npm install @insforge/sdk@latest

import { createClient } from '@insforge/sdk';

const insforge = createClient({
  baseUrl: 'https://your-app.us-east.insforge.app',
  anonKey: 'your-anon-key'  // Optional: for public/unauthenticated requests
});

Create a new user account with email and password.

Parameters

email (string, required) - User’s email address
password (string, required) - User’s password
name (string, optional) - User’s display name
options (object, optional) - Additional options
- emailRedirectTo (string, optional) - Custom URL to redirect to after email verification. It’s a fallback if you didn’t set default redirect URL configured in your dashboard.

Returns

{
  data: {
    user?: { id, email, emailVerified, providers, createdAt, updatedAt, profile, metadata },
    accessToken: string | null,
    requireEmailVerification?: boolean,
    redirectTo?: string,
    csrfToken?: string | null
  } | null,
  error: Error | null
}

When requireEmailVerification is true, accessToken will be null until the user verifies their email. InsForge sends a verification email with either a link or a 6-digit code, based on your dashboard configuration (verifyEmailMethod). For code verification, implement a page that prompts the user to enter the code (see verifyEmail()). For link verification, redirect users to the sign-in page—the insforge backend handles verification automatically when the link is clicked.

Example

const { data, error } = await insforge.auth.signUp({
  email: '[email protected]',
  password: 'secure_password123',
  name: 'John Doe',
});

if (data?.requireEmailVerification) {
  // For code verification: redirect to page where user enters the 6-digit code
  // For link verification: redirect to sign-in page to await email link click
  console.log('Please verify your email');
} else if (data?.accessToken) {
  // User is signed in (email verification disabled)
  console.log('Welcome!', data.user.email);
}

Output

{
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "emailVerified": false,
      "providers": ["email"],
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z",
      "profile": {
        "name": "John Doe",
        "avatar_url": null
      },
      "metadata": {}
    },
    "requireEmailVerification": true,
    "accessToken": null,
    "redirectTo": "https://app.example.com/verify-email",
    "csrfToken": null
  },
  "error": null
}

signInWithPassword()

Parameters

email (string, required) - User’s email address
password (string, required) - User’s password

Returns

{
  data: {
    user: { id, email, emailVerified, providers, createdAt, updatedAt, profile, metadata },
    accessToken: string,
    redirectTo?: string,
    csrfToken?: string | null
  } | null,
  error: Error | null
}

Example

const { data, error } = await insforge.auth.signInWithPassword({
  email: '[email protected]',
  password: 'secure_password123',
});

if (data) {
  console.log('Signed in as:', data.user.email);
  // Optional: redirect to configured URL
  if (data.redirectTo) {
    window.location.href = data.redirectTo;
  }
}

Output

{
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "emailVerified": true,
      "providers": ["email"],
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z",
      "profile": {
        "name": "John Doe",
        "avatar_url": "https://example.com/avatar.jpg"
      },
      "metadata": {}
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "redirectTo": "https://app.example.com/dashboard",
    "csrfToken": "5758d38259fb..."
  },
  "error": null
}

signInWithOAuth()

Start OAuth authentication flow with supported providers (Google, GitHub, Microsoft, Discord, and more).

Parameters

provider (string, required) - OAuth provider name (e.g., ‘google’, ‘github’, ‘microsoft’, ‘discord’)
redirectTo (string, optional) - URL to redirect after authentication
skipBrowserRedirect (boolean, optional) - If true, returns OAuth URL without auto-redirecting (for mobile apps)

Returns

{
  data: { url?: string, provider?: string },
  error: Error | null
}

After OAuth redirect, SDK automatically detects callback parameters and saves session. No manual handling needed.

Example

// Default: auto-redirect
await insforge.auth.signInWithOAuth({
  provider: 'google',
  redirectTo: 'http://localhost:3000/dashboard',
});
// Browser immediately redirects to Google

// skipBrowserRedirect: get URL for manual handling
const { data } = await insforge.auth.signInWithOAuth({
  provider: 'google',
  skipBrowserRedirect: true,
});

window.location.href = data.url; // Redirect when ready

Output

{
  "data": {
    "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...",
    "provider": "google"
  },
  "error": null
}

signOut()

Sign out the current user and clear session.

Parameters

None

Returns

{
  error: Error | null;
}

Example

const { error } = await insforge.auth.signOut();

Output

{
  "error": null
}

getCurrentSession()

Get the current session. If no active session exists, attempts to refresh using the httpOnly cookie. Call this on app initialization to restore user sessions automatically.

Parameters

None

Returns

{
  data: {
    session: {
      accessToken: string,
      user: { id, email, emailVerified, providers, createdAt, updatedAt, profile, metadata },
      expiresAt?: Date
    } | null
  },
  error: Error | null
}

Example

const { data, error } = await insforge.auth.getCurrentSession();

if (data.session) {
  console.log('Token:', data.session.accessToken);
  console.log('User:', data.session.user.email);

  // Check if session is expired
  if (data.session.expiresAt && new Date() > data.session.expiresAt) {
    console.log('Session expired');
  }
}

Output

{
  "data": {
    "session": {
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expiresAt": "2024-01-22T10:00:00.000Z",
      "user": {
        "id": "usr_abc123",
        "email": "[email protected]",
        "emailVerified": true,
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:00:00Z",
        "providers": ["email"],
        "profile": {
          "name": "John Doe",
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "metadata": {}
      }
    }
  },
  "error": null
}

getProfile()

Get any user’s public profile by ID. Returns a flat profile object with all fields at the top level.

Parameters

userId (string, required) - User ID to fetch profile for

Returns

{
  data: {
    id: string,
    name?: string,
    avatar_url?: string,
    createdAt?: string,
    updatedAt?: string,
    ...customFields
  } | null,
  error: Error | null
}

Example

const { data, error } = await insforge.auth.getProfile('usr_xyz789');

if (data) {
  console.log(data.name);
  console.log(data.avatar_url);
}

Output

{
  "data": {
    "id": "usr_xyz789",
    "name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg",
    "bio": "Full-stack developer",
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  },
  "error": null
}

setProfile()

Update current user’s profile in users table. Supports any dynamic fields and returns the updated profile as a flat object.

Parameters

profile (object) - A key-value map of profile fields to update. Any fields are accepted.

Common fields:

name (predefined, string) - User’s display name
avatar_url (predefined, string) - Profile picture URL

Returns

{
  data: {
    id: string,
    name?: string,
    avatar_url?: string,
    createdAt?: string,
    updatedAt?: string,
    ...customFields
  } | null,
  error: Error | null
}

Example

const { data, error } = await insforge.auth.setProfile({
  name: 'JohnDev',
  bio: 'Full-stack developer',
  avatar_url: 'https://example.com/avatar.jpg',
  custom_field: 'any value', // Any custom fields are supported
});

Output

{
  "data": {
    "id": "usr_abc123",
    "name": "JohnDev",
    "avatar_url": "https://example.com/avatar.jpg",
    "bio": "Full-stack developer",
    "custom_field": "any value",
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z"
  },
  "error": null
}

resendVerificationEmail()

Resend email verification when the previous OTP has expired or was not received. Uses the method configured in auth settings (verifyEmailMethod). When method is code, sends a 6-digit numeric code. When method is link, sends a magic link.

This endpoint prevents user enumeration by returning success even if the email doesn’t exist.

Parameters

email (string, required) - User’s email address
options (object, optional) - Additional options
- emailRedirectTo (string, optional) - Custom URL to redirect to after email verification. It’s a fallback if you didn’t set default redirect URL configured in your dashboard.

Returns

{
  data: { success: boolean, message: string } | null,
  error: Error | null
}

Example

const { data, error } = await insforge.auth.resendVerificationEmail({
  email: '[email protected]',
});

if (data?.success) {
  console.log('Verification email sent!');
}

Output

{
  "data": {
    "success": true,
    "message": "Verification email sent"
  },
  "error": null
}

verifyEmail()

Verify email address using the method configured in auth settings (verifyEmailMethod):

Code verification: Provide both email and otp (6-digit numeric code)
Link verification: Provide only otp (64-character hex token from magic link)

Successfully verified users will receive a session token.

Parameters

email (string, optional) - User’s email address (required for code verification)
otp (string, required) - 6-digit code or 64-character token from magic link

Returns

{
  data: {
    accessToken: string,
    user: { id, email, emailVerified, ... },
    redirectTo?: string
  } | null,
  error: Error | null
}

Example

// Code verification (when verifyEmailMethod is 'code')
const { data, error } = await insforge.auth.verifyEmail({
  email: '[email protected]',
  otp: '123456',
});

// Link verification (when verifyEmailMethod is 'link')
// Token is extracted from the magic link URL
const { data, error } = await insforge.auth.verifyEmail({
  otp: 'a1b2c3d4e5f6...', // 64-character token from URL
});

if (data) {
  console.log('Email verified!', data.accessToken);
}

Output

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "emailVerified": true
    },
    "redirectTo": "https://app.example.com/dashboard"
  },
  "error": null
}

sendResetPasswordEmail()

Send password reset email using the method configured in auth settings (resetPasswordMethod). When method is code, sends a 6-digit numeric code for two-step flow. When method is link, sends a magic link.

This endpoint prevents user enumeration by returning success even if the email doesn’t exist.

Parameters

email (string, required) - User’s email address

Returns

{
  data: { success: boolean, message: string } | null,
  error: Error | null
}

Example

const { data, error } = await insforge.auth.sendResetPasswordEmail({
  email: '[email protected]',
});

if (data?.success) {
  console.log('Password reset email sent!');
}

Output

{
  "data": {
    "success": true,
    "message": "Password reset email sent"
  },
  "error": null
}

exchangeResetPasswordToken()

Exchange a 6-digit reset password code for a reset token. This is step 1 of the two-step password reset flow (only used when resetPasswordMethod is code).

This endpoint is not used when resetPasswordMethod is link (magic link flow is direct).

Parameters

email (string, required) - User’s email address
code (string, required) - 6-digit code from the email

Returns

{
  data: { token: string, expiresAt: string } | null,
  error: Error | null
}

Example

const { data, error } = await insforge.auth.exchangeResetPasswordToken({
  email: '[email protected]',
  code: '123456',
});

if (data) {
  // Use token to reset password
  await insforge.auth.resetPassword({
    newPassword: 'newSecurePassword123',
    otp: data.token,
  });
}

Output

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": "2024-01-15T11:00:00Z"
  },
  "error": null
}

resetPassword()

Reset user password with a token. The token can be:

Magic link token: 64-character hex token from sendResetPasswordEmail when method is link
Reset token: From exchangeResetPasswordToken after code verification when method is code

Parameters

newPassword (string, required) - New password for the user
otp (string, required) - Reset token or magic link token

Returns

{
  data: { message: string, redirectTo?: string } | null,
  error: Error | null
}

Example

// Code method flow: after exchangeResetPasswordToken
const { data, error } = await insforge.auth.resetPassword({
  newPassword: 'newSecurePassword123',
  otp: resetToken, // Token from exchangeResetPasswordToken
});

// Link method flow: token from URL params
const { data, error } = await insforge.auth.resetPassword({
  newPassword: 'newSecurePassword123',
  otp: 'a1b2c3d4e5f6...', // 64-character token from magic link URL
});

if (data) {
  console.log('Password reset successful!');
}

Output

{
  "data": {
    "message": "Password reset successfully",
    "redirectTo": "https://app.example.com/login"
  },
  "error": null
}

Error Handling

All auth methods return structured errors:

const { data, error } = await insforge.auth.signInWithPassword({
  email: '[email protected]',
  password: 'wrong_password',
});

if (error) {
  console.error(error.statusCode); // 401
  console.error(error.error); // 'INVALID_CREDENTIALS'
  console.error(error.message); // 'Invalid login credentials'
  console.error(error.nextActions); // 'Check email and password'
}

Getting Started

Core Concepts

Changelog

​signUp()

​Parameters

​Returns

​Example

​Output

​signInWithPassword()

​Parameters

​Returns

​Example

​Output

​signInWithOAuth()

​Parameters

​Returns

​Example

​Output

​signOut()

​Parameters

​Returns

​Example

​Output

​getCurrentSession()

​Parameters

​Returns

​Example

​Output

​getProfile()

​Parameters

​Returns

​Example

​Output

​setProfile()

​Parameters

​Returns

​Example

​Output

​resendVerificationEmail()

​Parameters

​Returns

​Example

​Output

​verifyEmail()

​Parameters

​Returns

​Example

​Output

​sendResetPasswordEmail()

​Parameters

​Returns

​Example

​Output

​exchangeResetPasswordToken()

​Parameters

​Returns

​Example

​Output

​resetPassword()

​Parameters

​Returns

​Example

​Output

​Error Handling

signUp()

Parameters

Returns

Example

Output

signInWithPassword()

Parameters

Returns

Example

Output

signInWithOAuth()

Parameters

Returns

Example

Output

signOut()

Parameters

Returns

Example

Output

getCurrentSession()

Parameters

Returns

Example

Output

getProfile()

Parameters

Returns

Example

Output

setProfile()

Parameters

Returns

Example

Output

resendVerificationEmail()

Parameters

Returns

Example

Output

verifyEmail()

Parameters

Returns

Example

Output

sendResetPasswordEmail()

Parameters

Returns

Example

Output

exchangeResetPasswordToken()

Parameters

Returns

Example

Output

resetPassword()

Parameters

Returns

Example

Output

Error Handling