Authentication SDK Reference

Installation

npm install @insforge/sdk@latest

yarn add @insforge/sdk@latest

pnpm add @insforge/sdk@latest

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

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

Find the anon key with npx @insforge/cli secrets get ANON_KEY, or in the dashboard: click Install and open API Keys. 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
redirectTo (string, optional) - Used for link-based email verification. The email link always opens an InsForge backend endpoint first; after the token is verified, InsForge redirects the browser to this URL with the verification result. Required when verifyEmailMethod is set to link. This URL must be included in allowedRedirectUrls. Recommended: use your app’s sign-in page.

Returns

{
  data: {
    user?: { id, email, emailVerified, providers, createdAt, updatedAt, profile, metadata },
    accessToken: string | null,
    requireEmailVerification?: boolean,
    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, provide a redirectTo URL that should receive the browser after InsForge verifies the token. Recommended: use your sign-in page as redirectTo, then show a success message and ask the user to sign in with their email and password.

Example

const { data, error } = await insforge.auth.signUp({
  email: 'user@example.com',
  password: 'secure_password123',
  name: 'John Doe',
  redirectTo: 'http://localhost:3000/sign-in',
});

if (data?.requireEmailVerification) {
  // For code verification: redirect to page where user enters the 6-digit code
  // For link verification: wait for the user to click the email link
  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": "user@example.com",
      "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,
    "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,
    csrfToken?: string | null
  } | null,
  error: Error | null
}

Example

const { data, error } = await insforge.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secure_password123',
});

if (data) {
  console.log('Signed in as:', data.user.email);
}

Output

{
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "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...",
    "csrfToken": "5758d38259fb..."
  },
  "error": null
}

signInWithOAuth()

Start OAuth authentication flow with configured providers (built-in providers like Google/GitHub, plus any custom provider key configured from the dashboard).

Parameters

provider (string, required) - OAuth provider key (e.g., google, github, or custom provider key like okta-company)
redirectTo (string, required) - URL to redirect after authentication
additionalParams (Record<string, string>, optional) - Provider-specific OAuth hints such as Google’s prompt=select_account
skipBrowserRedirect (boolean, optional) - If true, returns OAuth URL without auto-redirecting (for server-rendered or mobile flows)

Returns

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

After OAuth redirect, SDK automatically detects the callback insforge_code, exchanges it for a session, and saves the session automatically.

Example

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

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

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

additionalParams is for provider-specific optional hints only. Do not pass server-owned OAuth fields such as client_id, redirect_uri, code_challenge, state, response_type, or scope; InsForge sets those values on the server and ignores colliding client-provided keys.

Custom providers must be configured first in the InsForge dashboard under Auth Methods with client credentials and an OIDC discovery URL.

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
}

getCurrentUser()

Get the currently signed-in user. For browser apps, call auth.getCurrentUser() during startup. If a valid httpOnly refresh cookie is present, the SDK will refresh the session automatically before returning the user. For server mode, call refreshSession({ refreshToken }) explicitly when you need to refresh an expired access token.

Parameters

None

Returns

{
  data: {
    user: { id, email, emailVerified, providers, createdAt, updatedAt, profile, metadata } | null
  },
  error: Error | null
}

Example

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

if (data.user) {
  console.log('User:', data.user.email);
}

Output

{
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "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 browser verification link that goes through an InsForge backend endpoint first.

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

Parameters

email (string, required) - User’s email address
redirectTo (string, optional) - Used for link-based email verification. The email link always opens an InsForge backend endpoint first; after the token is verified, InsForge redirects the browser to this URL with the verification result. Required when verifyEmailMethod is set to link. This URL must be included in allowedRedirectUrls. Recommended: use your app’s sign-in page.

Returns

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

Example

const { data, error } = await insforge.auth.resendVerificationEmail({
  email: 'user@example.com',
  redirectTo: 'http://localhost:3000/sign-in',
});

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

Output

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

verifyEmail()

Verify an email address with a 6-digit code. For link-based verification, users should click the email link, which opens GET /api/auth/email/verify-link in the browser. Successfully verified users who use this code endpoint will receive a session token. For link-based verification, your frontend should handle the browser redirect like this:

Success: ?insforge_status=success&insforge_type=verify_email
Error: ?insforge_status=error&insforge_type=verify_email&insforge_error=...
insforge_status: Result of the browser link flow. For verification, values are success or error.
insforge_type: Flow identifier. For verification links this is always verify_email.
insforge_error: Present only when insforge_status=error. Human-readable error message for display or logging.

Recommended handling: use your sign-in page as redirectTo. When insforge_status=success, show a confirmation message and ask the user to sign in with their email and password.

Parameters

email (string, required) - User’s email address
otp (string, required) - 6-digit verification code

Returns

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

Example

const { data, error } = await insforge.auth.verifyEmail({
  email: 'user@example.com',
  otp: '123456',
});

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

Output

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "emailVerified": true
    }
  },
  "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 browser reset link that goes through an InsForge backend endpoint first.

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

Parameters

email (string, required) - User’s email address
redirectTo (string, optional) - Used for link-based password reset. The email link always opens an InsForge backend endpoint first; InsForge then redirects the browser to this URL with the reset token in the query string so your app can render its own reset-password page. Required when resetPasswordMethod is set to link. This URL must be included in allowedRedirectUrls. Recommended: use your app’s dedicated reset-password page.

Returns

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

Example

const { data, error } = await insforge.auth.sendResetPasswordEmail({
  email: 'user@example.com',
  redirectTo: 'http://localhost:3000/reset-password',
});

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, because the browser reset-link flow uses the emailed link token directly.

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: 'user@example.com',
  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: Provided in the reset page URL 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

For link-based password reset, your frontend should handle the browser redirect like this:

Ready to reset: ?token=...&insforge_status=ready&insforge_type=reset_password
Error: ?insforge_status=error&insforge_type=reset_password&insforge_error=...
token: Present only when insforge_status=ready. Pass this value to resetPassword({ otp }).
insforge_status: Result of the browser link flow. For reset links, values are ready or error.
insforge_type: Flow identifier. For reset links this is always reset_password.
insforge_error: Present only when insforge_status=error. Human-readable error message for display or logging.

Only render the reset-password form when insforge_status=ready and token is present.

Returns

{
  data: { message: 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 the reset page URL
const { data, error } = await insforge.auth.resetPassword({
  newPassword: 'newSecurePassword123',
  otp: 'a1b2c3d4e5f6...', // Token from the magic link URL
});

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

Output

{
  "data": {
    "message": "Password reset successfully. Please login with your new password."
  },
  "error": null
}

Error Handling

All auth methods return structured errors:

const { data, error } = await insforge.auth.signInWithPassword({
  email: 'user@example.com',
  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'
}

​Installation

​signUp()

​Parameters

​Returns

​Example

​Output

​signInWithPassword()

​Parameters

​Returns

​Example

​Output

​signInWithOAuth()

​Parameters

​Returns

​Example

​Output

​signOut()

​Parameters

​Returns

​Example

​Output

​getCurrentUser()

​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

Installation

signUp()

Parameters

Returns

Example

Output

signInWithPassword()

Parameters

Returns

Example

Output

signInWithOAuth()

Parameters

Returns

Example

Output

signOut()

Parameters

Returns

Example

Output

getCurrentUser()

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