baxcloud_verify_sdk 1.3.1

BaxCloud Verify SDK for Flutter — SMS OTP verification via BaxVerify

BaxCloud Verify SDK for Flutter

SMS OTP verification for iOS and Android apps via BaxVerify.

Current version: baxcloud_verify_sdk 1.3.1

What's new in 1.3.1

• Sends X-Bundle-Id on all API requests (for client-key bundle allowlists)
• Optional bundleId on BaxCloudVerifyConfig; auto-detected via package_info_plus when omitted
• Prefer a client key (bax_pk_…) with the BaxVerify scope for sendOtp / verifyOtp in the app

Installation

dependencies:
  baxcloud_verify_sdk: ^1.3.1

flutter pub get

Quick Start

import 'package:baxcloud_verify_sdk/baxcloud_verify_sdk.dart';

final verify = BaxCloudVerifyClient(
  config: BaxCloudVerifyConfig(
    projectId: 'your-project-id',
    apiKey: 'bax_pk_your-client-key', // client key with BaxVerify scope
    // bundleId: 'com.example.app', // optional — auto-detected when omitted
    debug: true,
  ),
);

// Send OTP
final sent = await verify.sendOtp(
  SendOtpOptions(phone: '[phone]', purpose: BaxVerifyOtpPurpose.login),
);

// Verify OTP — returns a short-lived accessToken
final result = await verify.verifyOtp(
  VerifyOtpOptions(phone: '[phone]', code: '123456'),
);
print('Token expires in ${result.expiresIn}s');

API keys & optional bundleId

Use in app	Use on backend
Client key bax_pk_… + BaxVerify scope for sendOtp / verifyOtp	Server key bax_sk_… for validate-token, logs, stats

If the client key has Allowed bundle IDs in the dashboard, the SDK sends X-Bundle-Id automatically (or use bundleId: to override).

BaxCloudVerifyConfig(
  projectId: 'your-project-id',
  apiKey: 'bax_pk_…',
  bundleId: 'com.mycompany.myapp', // optional override
)

Docs: Authentication

Verification access token

After a successful verifyOtp, BaxVerify returns a short-lived JWT (accessToken) that proves the phone number was verified. Use it with any backend or auth system:

1. Your API — client sends accessToken; your server calls POST /auth/sms/validate-token and issues your own session/JWT.
2. Third-party auth — pass result.externalAuth ({ id: phone, token }) to providers that support custom auth adapters (e.g. Parse Server logInWith).
3. Server-side SDK — call validateVerificationToken() from a trusted backend (not from the mobile app with a secret key).

Tokens are single-use by default when validated with consume: true.

Example: exchange token on your backend

// Mobile app — after verifyOtp
final result = await verify.verifyOtp(...);
await http.post(
  Uri.parse('https://your-api.com/auth/phone-login'),
  headers: {'Content-Type': 'application/json'},
  body: jsonEncode({
    'phone': result.phone,
    'baxverifyToken': result.accessToken,
  }),
);

// Your backend
const res = await fetch('https://api.baxcloud.tech/v1/auth/sms/validate-token', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${BAXCLOUD_API_KEY}`,
    'X-Project-Id': PROJECT_ID,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ token: baxverifyToken, consume: true }),
});
const { data } = await res.json();
// data.phone is verified — issue your session JWT, create user, etc.

Parse Server phone login

BaxVerify proves the phone; Parse Server issues the user session. Your Parse Server validates the BaxVerify JWT — the BaxCloud API key stays on the server only.

Flutter client

dependencies:
  baxcloud_verify_sdk: ^1.3.1
  parse_server_sdk: ^6.0.0

import 'package:parse_server_sdk/parse_server_sdk.dart';
import 'package:baxcloud_verify_sdk/baxcloud_verify_sdk.dart';

await Parse().initialize(
  'YOUR_PARSE_APP_ID',
  'https://your-parse-server.com/parse',
  clientKey: 'YOUR_PARSE_CLIENT_KEY',
);

// After sendOtp + user enters SMS code:
final result = await verify.verifyOtp(
  VerifyOtpOptions(phone: '[phone]', code: code),
);

final authData = result.externalAuth!; // { id: phone, token: accessToken }

final response = await ParseUser.logInWith('baxverify', authData);
if (response.success) {
  final user = response.result as ParseUser;
  print(user.sessionToken);
}

Full example: example/parse_phone_login.dart

Parse Server (Node.js)

npm install @baxcloud/parse-server-baxverify

auth: {
  baxverify: { module: '@baxcloud/parse-server-baxverify' },
},

Set BAXCLOUD_PROJECT_ID and BAXCLOUD_API_KEY on Parse Server. See Parse Server docs.

Prerequisites

1. Enable BaxVerify on your BaxCloud project (Dashboard → BaxVerify).
2. Create a client API key (bax_pk_…) with the BaxVerify scope (and optional bundle allowlist).
3. Complete BaxVerify setup: rent a phone number and/or register a Sender ID.

Production tip: Keep validate-token / logs / stats on your backend with a server key (bax_sk_…). Mobile apps should use a client key for send / verify only.

API Reference

Method	Description
sendOtp(SendOtpOptions)	Send SMS verification code
verifyOtp(VerifyOtpOptions)	Verify code; returns accessToken
validateVerificationToken(...)	Server-side token validation (use bax_sk_)
getStats({days})	Usage stats (sent, verified, failed) — server key
listLogs({phone, status, page})	Paginated delivery logs — server key

Authentication

All requests use:

Authorization: Bearer <api_key>
X-Project-Id: <project_id>
X-Api-Key: <api_key>
X-Bundle-Id: <auto or config.bundleId>   # sent by this SDK

Error Handling

API errors include a stable code and optional details.helpUrl. BaxVerifyException exposes code, message, and helpUrl:

try {
  await verify.sendOtp(SendOtpOptions(phone: '[phone]', purpose: 'LOGIN'));
} on BaxVerifyException catch (e) {
  switch (e.code) {
    case 'BAXVERIFY_FEATURE_DISABLED':
      // e.helpUrl → enable BaxVerify under Project → Features
      break;
    case 'BAXVERIFY_SENDER_NOT_CONFIGURED':
      // e.helpUrl → BaxVerify Setup
      break;
    case 'BAXVERIFY_INSUFFICIENT_CREDITS':
      // e.helpUrl → Billing
      break;
    default:
      print('${e.statusCode} ${e.code}: ${e.message}');
  }
}

Full list: Error codes

Documentation

• BaxVerify docs
• Flutter SDK docs
• Node.js SDK (server-side — recommended for API keys)
• Dashboard setup

License

See LICENSE.