BaxCloud Verify SDK for Node.js

Server-side SMS OTP verification via BaxVerify — for Express, NestJS, Next.js API routes, and any Node.js backend.

For BaxVerify webhook verification (and other BaxCloud product webhooks), use @baxcloud/baxcloud-server-sdk alongside this package.

Product-specific SDKs:

• @baxcloud/baxstream — docs — video conversion + AI
• @baxcloud/baxmail — docs — transactional email
• @baxcloud/baxverify — docs — SMS OTP verification
• @baxcloud/baxlinks — docs — deep linking & attribution

Installation

npm install @baxcloud/baxverify

pnpm add @baxcloud/baxverify

Quick Start

import { BaxCloudVerifyClient } from '@baxcloud/baxverify';

const verify = new BaxCloudVerifyClient({
  projectId: process.env.BAXCLOUD_PROJECT_ID!,
  apiKey: process.env.BAXCLOUD_API_KEY!,
});

// 1. Send OTP (from your API route)
await verify.sendOtp({ phone: '+14155552671', purpose: 'LOGIN' });

// 2. Verify code (from your API route)
const result = await verify.verifyOtp({
  phone: '+14155552671',
  code: '123456',
});

// 3. Validate proof token when mobile client sends accessToken back
const proof = await verify.validateVerificationToken({
  token: result.accessToken,
});

console.log('Verified phone:', proof.phone);

Phone login flow (recommended)

sequenceDiagram
  participant App
  participant API as Your Node API
  participant BV as BaxVerify

  App->>API: POST /auth/otp/send { phone }
  API->>BV: sendOtp()
  App->>API: POST /auth/otp/verify { phone, code }
  API->>BV: verifyOtp()
  BV-->>API: accessToken
  API-->>App: accessToken (or your session JWT)

  Note over App,API: Later — exchange proof for session
  App->>API: POST /auth/phone-login { accessToken }
  API->>BV: validateVerificationToken()
  API-->>App: your session token

Verification access token

After verifyOtp, BaxVerify returns a short-lived JWT (accessToken). Validate it server-side before creating your session:

const proof = await verify.validateVerificationToken({
  token: req.body.baxverifyToken,
  consume: true, // default — single use
});

// proof.phone is verified — create user session, Parse auth, etc.

BaxCloudVerifyClient.externalAuthFromVerifyResult(result) returns { id, token } for third-party auth adapters.

API Reference

| Method | Description | |--------|-------------| | sendOtp(options) | Send SMS verification code | | verifyOtp(options) | Verify code; returns accessToken | | validateVerificationToken(options) | Validate proof JWT | | getStats(days?) | Usage statistics | | listLogs(options?) | Paginated delivery logs |

Express example

See examples/express-phone-login.ts.

Parse Server auth adapter

Use BaxVerify as a custom auth provider so Flutter/web clients can call ParseUser.logInWith('baxverify', { id, token }).

Install the published Parse adapter:

npm install @baxcloud/parse-server-baxverify

See @baxcloud/parse-server-baxverify and the Parse Server guide.

Parse Server config

const { ParseServer } = require('parse-server');

new ParseServer({
  // ...
  auth: {
    baxverify: { module: '@baxcloud/parse-server-baxverify' },
  },
});

Set BAXCLOUD_PROJECT_ID and BAXCLOUD_API_KEY on Parse Server, or pass projectId / apiKey in the baxverify auth config.

Flutter client

After verifyOtp, pass result.externalAuth to Parse:

await ParseUser.logInWith('baxverify', result.externalAuth!);

See the Flutter SDK on pub.dev and Flutter Parse guide.

Error handling

API errors use a stable code and optional details.helpUrl (dashboard link). The SDK exposes them on BaxVerifyError:

import { BaxVerifyError } from '@baxcloud/baxverify';

try {
  await verify.sendOtp({ phone: '+14155552671', purpose: 'LOGIN' });
} catch (err) {
  if (err instanceof BaxVerifyError) {
    switch (err.code) {
      case 'BAXVERIFY_FEATURE_DISABLED':
        // err.details?.helpUrl → enable BaxVerify under Project → Features
        break;
      case 'BAXVERIFY_SENDER_NOT_CONFIGURED':
        // err.details?.helpUrl → BaxVerify Setup (phone number / Sender ID)
        break;
      case 'BAXVERIFY_INSUFFICIENT_CREDITS':
        // err.details?.helpUrl → Billing
        break;
      default:
        console.error(err.statusCode, err.code, err.message);
    }
  }
}

| Code | Typical cause | |------|----------------| | BAXVERIFY_FEATURE_DISABLED | Enable BaxVerify on the project | | BAXVERIFY_SENDER_NOT_CONFIGURED | Rent a number or register Sender ID | | BAXVERIFY_INSUFFICIENT_CREDITS | Add billing credits | | BAXVERIFY_OTP_EXPIRED / BAXVERIFY_OTP_INVALID | Resend or re-enter code | | BAXVERIFY_TOKEN_INVALID / BAXVERIFY_TOKEN_CONSUMED | Re-verify phone |

Full list: Error codes

Prerequisites

1. Enable BaxVerify on your BaxCloud project.
2. Create an API key with BaxVerify enabled.
3. Complete setup: phone number and/or Sender ID.

Related SDKs

• @baxcloud/baxcloud-server-sdk — docs — webhooks, rooms, streaming, PK Battle
• @baxcloud/baxstream — docs — video conversion + AI
• @baxcloud/baxmail — docs — transactional email
• @baxcloud/baxlinks — docs — deep linking & attribution
• @baxcloud/parse-server-baxverify — docs — Parse Server phone auth
• BaxVerify Flutter SDK — docs — mobile clients

License

MIT — see LICENSE.

Support

• Help: https://baxcloud.tech/dashboard/help
• Contact: https://baxcloud.tech/contact
• Documentation: https://baxcloud.tech/docs/baxverify/sdk/node
• Email: [email protected]