BaxVerify

BaxVerify Documentation

SMS OTP verification — send codes, verify phones, and track delivery from your app or backend.

Prerequisites

Enable BaxVerify on your project (Dashboard → BaxVerify → Setup).
Rent a phone number and/or register a Sender ID for SMS delivery.
Create an API key with the BaxVerify feature enabled.

Authentication

All BaxVerify REST and SDK traffic uses https://api.baxcloud.tech/v1 (fixed — not configurable in SDKs). Requests require:

Authorization: Bearer YOUR_API_KEY
X-Project-Id: YOUR_PROJECT_ID
Content-Type: application/json

Quick Start

1. Send OTP

1curl -X POST https://api.baxcloud.tech/v1/auth/sms/send \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "X-Project-Id: YOUR_PROJECT_ID" \
4  -H "Content-Type: application/json" \
5  -d '{"phone": "+14155552671", "purpose": "LOGIN"}'

2. Verify OTP

1curl -X POST https://api.baxcloud.tech/v1/auth/sms/verify \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "X-Project-Id: YOUR_PROJECT_ID" \
4  -H "Content-Type: application/json" \
5  -d '{"phone": "+14155552671", "code": "123456"}'

Returns a short-lived accessToken (JWT) proving the phone was verified.

3. Validate token (your backend)

1curl -X POST https://api.baxcloud.tech/v1/auth/sms/validate-token \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "X-Project-Id: YOUR_PROJECT_ID" \
4  -H "Content-Type: application/json" \
5  -d '{"token": "ACCESS_TOKEN_FROM_VERIFY", "consume": true}'

Universal server-side check — use with your own auth, Parse, or any system that accepts an id + token proof.

Verification access token

BaxVerify is not a session provider — it issues a proof token after OTP success. Your backend validates it and creates whatever session you need.

Single-use by default when consume: true
15-minute TTL (configurable on the API server)
JWT claims: phone (sub), project, purpose, request id

{
  "verified": true,
  "phone": "+14155552671",
  "accessToken": "eyJhbG...",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Error codes

Failed BaxVerify API calls return a structured JSON envelope. Use error.code for programmatic handling and error.details.helpUrl to link users to the right dashboard page.

{
  "success": false,
  "error": {
    "code": "BAXVERIFY_FEATURE_DISABLED",
    "message": "BaxVerify is not enabled for this project. Enable it under Project → Features.",
    "details": {
      "projectId": "your-project-id",
      "helpUrl": "https://baxcloud.tech/dashboard/projects/your-project-id?tab=features",
      "docsUrl": "https://baxcloud.tech/docs/baxverify"
    }
  },
  "timestamp": "2026-06-06T12:00:00.000Z",
  "path": "/v1/auth/sms/send"
}

Code	HTTP	Message	What to do
BAXVERIFY_FEATURE_DISABLED	403	BaxVerify is not enabled for this project.	Enable BaxVerify under Project → Features (details.helpUrl).
BAXVERIFY_PLAN_NOT_INCLUDED	403	Your plan does not include BaxVerify.	Upgrade your subscription (details.helpUrl → Billing).
BAXVERIFY_API_KEY_SCOPE	403	API key lacks BaxVerify scope.	Create or edit an API key with BaxVerify enabled.
BAXVERIFY_SENDER_NOT_CONFIGURED	400	No SMS sender configured.	Rent a phone number and/or register a Sender ID in BaxVerify Setup (details.helpUrl).
BAXVERIFY_INSUFFICIENT_CREDITS	400	Insufficient credits for SMS delivery.	Add credits in Billing before sending (details.helpUrl).
BAXVERIFY_VERIFY_FEE_CREDITS	400	Insufficient credits for the verification fee.	Add credits in Billing (details.helpUrl).
BAXVERIFY_NO_SUBSCRIPTION	400	No active subscription for this project.	Subscribe or restore billing for the project.
BAXVERIFY_RATE_LIMIT	429	Rate limit exceeded.	Wait before sending or verifying another code.
BAXVERIFY_OTP_EXPIRED	400	Code expired or not found.	Call send again to request a new code.
BAXVERIFY_OTP_INVALID	400	Invalid verification code.	Ask the user to re-enter the code from SMS.
BAXVERIFY_OTP_MAX_ATTEMPTS	429	Too many failed attempts.	Request a new code via send.
BAXVERIFY_INVALID_PHONE	400	Phone number is not valid.	Use full international format with country code (e.g. +14155552671).
BAXVERIFY_SMS_SEND_FAILED	400	Failed to send SMS.	Check sender setup, destination number, and provider status.
BAXVERIFY_TOKEN_INVALID	401	Verification token is invalid or expired.	User must verify OTP again to obtain a new accessToken.
BAXVERIFY_TOKEN_CONSUMED	401	Verification token already used.	Tokens are single-use when consume: true — verify OTP again.
BAXVERIFY_PROJECT_INACTIVE	403	Project is not active.	Reactivate the project in the dashboard.
BAXVERIFY_PROJECT_HEADER_REQUIRED	400	X-Project-Id header is required.	Send X-Project-Id with every request.
BAXVERIFY_API_KEY_PROJECT_MISMATCH	403	API key does not belong to this project.	Use an API key created for the same project as X-Project-Id.

API Reference

Method	Path	Description
POST	/auth/sms/send	Send verification code
POST	/auth/sms/verify	Verify code; returns accessToken
POST	/auth/sms/validate-token	Validate proof token (server-side)
GET	/auth/sms/stats	Usage statistics
GET	/auth/sms/logs	Delivery logs

SDKs

SDKs only require projectId and apiKey — the API endpoint is built in.

Node.js (server)

Use from Express, NestJS, or Next.js API routes. Keep your API key on the server.

npm install @baxcloud/baxverify

Node.js SDK Guide

Flutter (mobile)

dependencies:
  baxcloud_verify_sdk: ^1.2.0

Flutter SDK Guide

Parse Server (auth adapter)

Phone login with ParseUser.logInWith('baxverify', authData) — validates BaxVerify JWT on your Parse Server.

npm install @baxcloud/parse-server-baxverify

Parse Server Guide

Parse Server

Use BaxVerify for SMS OTP, then ParseUser.logInWith('baxverify', authData) on Flutter. Parse Server validates the BaxVerify JWT with @baxcloud/parse-server-baxverify — API keys stay on the server.

Parse Server adapter — install & configure
Flutter client — send, verify, logInWith

Webhooks

BaxVerify emits webhook events you can subscribe to in Dashboard → Webhooks:

baxauth.otp.sent
baxauth.otp.verified
baxauth.otp.failed

Webhook documentation →

Product page

Learn more about BaxVerify