Skip to main content
This guide wires up silent verification in a web app, end to end: the browser runs header enrichment with the Web SDK, your backend completes the verification with the server-side API key, and the customer is recognized with nothing to type.

​
Architecture

The golden rule: the API key never leaves your server. The browser uses a short-lived sdkToken; your backend uses the X-API-KEY.
In the SDK, the encrypted proof is called authmatechCode and the operator id is MNOID. On the Verify API these map to encryptedMobileNumber and operatorId respectively.

​
Step 1 — Issue a short-lived SDK token from your backend

The browser needs an sdkToken to register a session. Mint or fetch it server-side and hand it to the page. Never embed the API key.

​
Step 2 — Run header enrichment in the browser

npm install authmatech-sdk-web

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

const sdk = new AuthmatechWebSDK({
  backendBaseURL: 'https://service.authmatech.com',
  clientId: process.env.NEXT_PUBLIC_AUTHMATECH_CLIENT_ID!,
  sdkToken: sdkTokenFromYourBackend, // short-lived, fetched per session
});

const { authmatechCode, MNOID, sdkSessionId } =
  await sdk.startHeaderEnrichment({ heUrl: 'https://he.operator.example.com/check' });

// Only ever display the masked value. The raw authmatechCode goes
// to YOUR backend over TLS — never to logs or analytics.
console.log('identity:', maskAuthmatechCode(authmatechCode));

await fetch('/api/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ authmatechCode, MNOID, sdkSessionId, mobileNumber }),
});
Under the hood, startHeaderEnrichment registers the session by calling POST /v1/api/sdk/session with the X-SDK-TOKEN and X-CLIENT-ID headers, then returns the sdkSessionId you forward to your backend.

​
Step 3 — Verify on your backend

Your endpoint receives the values from the browser and calls Verify with the secret API key: 
// POST /api/verify on YOUR server
app.post('/api/verify', async (req, res) => {
  const { authmatechCode, MNOID, sdkSessionId, mobileNumber } = req.body;

  const upstream = await fetch('https://service.authmatech.com/v1/api/verify', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': process.env.AUTHMATECH_API_KEY,   // server-side only
      'X-CLIENT-ID': process.env.AUTHMATECH_CLIENT_ID,
    },
    body: JSON.stringify({
      mobileNumber,
      encryptedMobileNumber: authmatechCode, // SDK authmatechCode → API field
      operatorId: MNOID,                     // SDK MNOID → API field
      serviceType: 'LOGIN',
      sdkSessionId,
    }),
  });

  res.status(upstream.status).json(await upstream.json());
});

​
Step 4 — Handle the fallback

Header enrichment needs an active mobile data connection. On Wi‑Fi, VPN, or some roaming networks the SDK throws (for example sdk_no_he_result). Catch it and fall back gracefully: 
try {
  const id = await sdk.startHeaderEnrichment({ heUrl });
  // ...verify
} catch (err) {
  // Show manual entry and route the customer through Stuck+
  showManualUnlock();
}
See Stuck+ for recovering these customers without dropping back to an OTP.

​
Requirements & constraints

  • Secure context — the page must be served over HTTPS.
  • Mobile data — enrichment can’t complete over Wi‑Fi or VPN.
  • Modern browsers — Chrome/Edge ≥ 95, Firefox ≥ 91, Safari/iOS Safari ≥ 15.
  • Never client-side keys — the SDK constructor rejects any field that looks like an API key or client secret.

Web SDK reference

Full configuration, methods, and error codes.

API: Register an SDK session

The session endpoint the SDK calls.