PostEx Auth SDK

1.4.0 verified Sat Apr 25 auth: no javascript

PostEx Authentication SDK (v1.4.0) provides a comprehensive solution for implementing secure authentication in web applications. Supports WebAuthn/Passkeys, OTP verification, magic link authentication, and DPoP (RFC 9449 compliant token binding). Features include multi-factor authentication, automatic token management, trusted device recognition, and browser feature detection. Ships TypeScript types. Active development with regular releases. Differentiators: includes DPoP support and passkey-first approach.

Common errors

error SyntaxError: Cannot use import statement outside a module ↓

cause ESM-only package used with CommonJS/Node.js without "type": "module" in package.json

fix

Add "type": "module" to package.json or use dynamic import().

error TypeError: auth.getStatus is not a function ↓

cause Wrong import: likely imported as default instead of named

fix

Use import { AuthSDK } from 'postex-auth-sdk-stage' instead of import AuthSDK from ...

error Request failed with status 400: {"error":"Unknown appId"} ↓

cause Passed an invalid appId value

fix

Use one of: 'xstak', 'postex', 'callcourier', 'postexglobal', 'postexsa'

Warnings

breaking ESM-only package: CommonJS require() will fail ↓

fix Use import syntax or dynamic import().

gotcha appId parameter only accepts predefined values: 'xstak', 'postex', 'callcourier', 'postexglobal', 'postexsa'. Using an unknown value may cause runtime errors. ↓

fix Use one of the allowed values. Default is 'postexglobal'.

gotcha initiateOTP() throws an error if both email and mobileNumber are missing/empty ↓

fix Provide at least one identifier: email or mobileNumber.

deprecated Passing a plain string to getStatus() or initiateAuth() may be deprecated in future versions ↓

fix Use object form: { email: '...' } or { mobileNumber: '...' }.

gotcha TypeScript types are exported as types only (not runtime values). Attempting to use them at runtime will throw. ↓

fix Use 'import type' for all type-only imports.

Install

npm install postex-auth-sdk-stage

yarn add postex-auth-sdk-stage

pnpm add postex-auth-sdk-stage

Imports

AuthSDK

wrong

const AuthSDK = require('postex-auth-sdk-stage')

correct

import { AuthSDK } from 'postex-auth-sdk-stage'

ESM-only package; CJS require fails. Use import or dynamic import.

AuthSDKConfig

wrong

import { AuthSDKConfig } from 'postex-auth-sdk-stage'

correct

import type { AuthSDKConfig } from 'postex-auth-sdk-stage'

TypeScript type import only; not a runtime value. Use 'import type' to avoid bundling issues.

AuthStatusResponse

wrong

import { AuthStatusResponse } from 'postex-auth-sdk-stage'

correct

import type { AuthStatusResponse } from 'postex-auth-sdk-stage'

TypeScript type import only; not a runtime value. Use 'import type' to avoid bundling issues.

InitiateAuthResponse

wrong

import { InitiateAuthResponse } from 'postex-auth-sdk-stage'

correct

import type { InitiateAuthResponse } from 'postex-auth-sdk-stage'

TypeScript type import only; not a runtime value. Use 'import type' to avoid bundling issues.

Quickstart

Initializes the AuthSDK with environment variables, checks status, initiates authentication, and handles passkey or OTP flows.

import { AuthSDK } from 'postex-auth-sdk-stage';

const auth = new AuthSDK({
  apiKey: process.env.API_KEY ?? '',
  appId: 'postexglobal'
});

async function authenticate() {
  try {
    const status = await auth.getStatus({ email: 'user@example.com' });
    const result = await auth.initiateAuth({ email: 'user@example.com' });
    if (result.status === 'webauthn_challenge') {
      const authResponse = await auth.authenticateWithPasskey({
        challenge: result.challenge,
        rp: result.rp,
        credentialIds: result.credentialIds
      });
      console.log('Passkey authenticated', authResponse);
    } else if (result.status === 'otp_sent') {
      const otpResponse = await auth.verifyOTP('123456');
      console.log('OTP verified', otpResponse);
    }
  } catch (error) {
    console.error('Authentication failed', error);
  }
}

authenticate();