Skip to main content
The Authmatech Web SDK (authmatech-sdk-web) runs silent mobile verification in the browser. It performs mobile-network header enrichment, registers a session with Authmatech using a short-lived SDK token, and returns an identity result your backend uses to complete verification. The SDK is designed so your API key never touches client code. For the end-to-end integration (including your backend), see Web verification.

​
Install

npm install authmatech-sdk-web
# or: pnpm add authmatech-sdk-web  /  yarn add authmatech-sdk-web
Current version: 1.1.0. Requires a secure context (HTTPS) and a modern browser: Chrome/Edge ≥ 95, Firefox ≥ 91, Safari/iOS Safari ≥ 15.

​
Configure

import { AuthmatechWebSDK } from 'authmatech-sdk-web';

const sdk = new AuthmatechWebSDK({
  backendBaseURL: 'https://service.authmatech.com', // HTTPS, required
  clientId: process.env.NEXT_PUBLIC_AUTHMATECH_CLIENT_ID!, // public, required
  sdkToken: sdkTokenFromYourBackend,                 // short-lived, required
  debug: false,                                      // optional
  allowUnregisteredSession: false,                   // optional fallback
});
​
backendBaseURL
string
required
The Authmatech API base URL. Must be HTTPS.
​
clientId
string
required
Your public Client ID. Sent as X-CLIENT-ID.
​
sdkToken
string
required
A short-lived, browser-scoped token your backend issues per session. Sent as X-SDK-TOKEN. It can only call /v1/api/sdk/session — never the server APIs.
​
debug
boolean
default:"false"
Verbose logging for development.
​
allowUnregisteredSession
boolean
default:"false"
If session registration fails, allow the flow to continue without an sdkSessionId. Off by default.
The constructor rejects any config field that looks like an API key or client secret (patterns matching api-key, x-api-key, client-secret). Never attempt to pass your server API key to the browser.

​
Methods

​
startHeaderEnrichment(options)

Runs the full flow — enrichment, then session registration — and resolves with the identity result. 
const result = await sdk.startHeaderEnrichment({
  heUrl: 'https://he.operator.example.com/check', // HTTPS operator endpoint
});
Returns AuthmatechIdentityResult: 
interface AuthmatechIdentityResult {
  authmatechCode: string; // encrypted proof of possession → API encryptedMobileNumber
  MNOID: string;          // operator id → API operatorId
  sdkSessionId: string;   // links the session for Shield/Detect
}
Forward authmatechCode, MNOID, and sdkSessionId to your backend, which calls POST /v1/api/verify with the API key. Map authmatechCode → encryptedMobileNumber and MNOID → operatorId.

​
registerSession(input)

Registers a session for an identity you already hold, returning { sdkSessionId }. startHeaderEnrichment calls this for you; use it directly only for advanced flows.

​
getVersion()

Returns the SDK version string.

​
maskAuthmatechCode(code)

A helper export that returns a masked, display-safe form of the identity token. Only ever show the masked value in UI or logs.

​
Safe display

import { maskAuthmatechCode } from 'authmatech-sdk-web';
console.log('identity:', maskAuthmatechCode(result.authmatechCode)); // safe
// Never log or render result.authmatechCode raw.

​
Error handling

The SDK throws AuthmatechSDKException with a stable ErrorCode:
CodeMeaning
sdk_invalid_configConstructor input failed validation
sdk_invalid_he_urlheUrl missing, malformed, or non-HTTPS
sdk_he_request_failedOperator enrichment returned a non-2xx status
sdk_no_he_resultOperator returned 200 but no identity token (often Wi‑Fi/VPN)
sdk_invalid_operator_responseOperator error code or malformed body
sdk_session_registration_failedAuthmatech rejected the session
sdk_timeoutRequest exceeded the timeout (default 8000 ms)
sdk_network_errorfetch failed (CORS, mixed content, DNS, …)
import { AuthmatechSDKException, ErrorCode } from 'authmatech-sdk-web';

try {
  const id = await sdk.startHeaderEnrichment({ heUrl });
} catch (e) {
  if (e instanceof AuthmatechSDKException && e.code === ErrorCode.sdk_no_he_result) {
    showManualUnlock(); // route to Stuck+
  } else {
    showGenericFallback();
  }
}
Header enrichment requires an active mobile data connection. On Wi‑Fi, VPN, or some roaming networks it cannot complete — always implement a fallback. Stuck+ is built for this.

Web verification guide

The full browser + backend flow.

API: SDK session

The endpoint the SDK registers against.