PostEx Auth SDK

1.3.0 verified Fri May 01 auth: no javascript

The PostEx Auth SDK (v1.3.0) provides a comprehensive authentication solution for web applications, supporting WebAuthn/passkeys, OTP, magic links, and DPoP token binding (RFC 9449). Built for PostEx ecosystem apps, it offers automatic token management, trusted device recognition, and browser feature detection. Ships TypeScript types. Release cadence: active development. Key differentiators: multi-factor with passkeys, ECDSA P-256 DPoP, and integrated session/device tracking.

Common errors

error TypeError: auth.getStatus is not a function ↓

cause Using a default import instead of named import, or using an older version.

fix

Use import { AuthSDK } from 'postex-auth-sdk-stage' and ensure version >= 1.0.0.

error AuthSDK is not a constructor ↓

cause Package is ESM-only and may be imported in a CommonJS context.

fix

Use dynamic import: const { AuthSDK } = await import('postex-auth-sdk-stage'); or switch to ES modules.

error Error: Both email and mobileNumber are missing ↓

cause Calling initiateOTP() without any identifier.

fix

Provide at least one identifier: auth.initiateOTP({ email: 'user@example.com' }) or { mobileNumber: '...' }.

error Uncaught (in promise) TypeError: Failed to parse URL from undefined/api/... ↓

cause apiKey is undefined or empty, causing an invalid base URL.

fix

Ensure apiKey is provided in the config and is non-empty.

Warnings

breaking Version 1.0.0 changed constructor signature: apiKey and appId moved from positional to config object. ↓

fix Use new AuthSDK({ apiKey, appId }) instead of new AuthSDK(apiKey, appId).

deprecated The appId 'postex' and 'callcourier' are deprecated and will be removed in v2. Use 'postexglobal' or 'postexsa'. ↓

fix Switch to appId: 'postexglobal' for global environment.

gotcha getStatus() with a string argument must be a valid email; mobile numbers are not accepted as string. Use object form for mobile. ↓

fix Use auth.getStatus({ mobileNumber: '...' }) instead of auth.getStatus('...').

gotcha initiateAuth() does not accept a mobile-only identifier via string; always use object form { mobileNumber }. ↓

fix Use auth.initiateAuth({ mobileNumber: '...' }).

deprecated The method 'authenticateWithMagicLink' was renamed to 'authenticateMagicLink' in v1.1.0. ↓

fix Use auth.authenticateMagicLink(token) instead.

Install

npm install postex-auth-sdk

yarn add postex-auth-sdk

pnpm add postex-auth-sdk

Imports

AuthSDK

wrong

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

correct

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

Named export, not default. ESM only; no CJS support.

AuthSDKConfig

wrong

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

correct

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

Only available with TypeScript or JSDoc type imports.

AuthStatusResponse

wrong

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

correct

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

Type-only import to avoid runtime overhead.

Quickstart

Initializes the SDK with API key and appId, checks auth status, then handles passkey or OTP based on the initiate response.

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

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

async function login(email: string) {
  const status = await auth.getStatus({ email });
  const initResult = await auth.initiateAuth({ email });
  if (initResult.status === 'webauthn_challenge') {
    const response = await auth.authenticateWithPasskey({
      challenge: initResult.challenge,
      rp: initResult.rp,
      credentialIds: initResult.credentialIds
    });
    console.log('Authenticated with passkey:', response);
  } else if (initResult.status === 'otp_sent') {
    const otpCode = await getUserOTP();
    const verifyResult = await auth.verifyOTP(otpCode);
    console.log('Authenticated with OTP:', verifyResult);
  }
}