Getting Started

This guide walks through a complete integration from zero to a working verification flow. Choose between raw HTTP calls or the TypeScript SDK — both are covered below.

Prerequisites

• An Emblem publisher account with an active integration
• Your secret API key (emb_sk_...), public key (emb_pk_...), and integration ID from the dashboard
• A server that can handle HTTPS callbacks

Testing integrations

Emblem currently operates a single public integration environment. Partners should integrate using production endpoints and issued API credentials. Internal staging environments are not intended for external use.

Use the public endpoint for integrations:

Verification testing can be performed using real API credentials during the integration process.

Key types

The secret key can call all endpoints. The public key can only start verification sessions — token validation always requires the secret key.

The flow

import crypto from 'node:crypto'

// Generate a random state parameter for CSRF protection
const state = crypto.randomBytes(16).toString('hex')

const response = await fetch('https://app.emblemapp.com/api/v1/verify/start', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMBLEM_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integration_id: process.env.EMBLEM_INTEGRATION_ID,
    callback_url: 'https://your-site.com/callback',
    state,
  }),
})

const { session_id, redirect_url, expires_at } = await response.json()

{
  "session_id": "emb_sess_abc123...",
  "redirect_url": "https://app.emblemapp.com/verify/emb_sess_abc123...?sat=...",
  "expires_at": "2026-01-01T00:10:00.000Z"
}

res.redirect(redirect_url)

https://your-site.com/callback?result_token=emb_rt_...&session_id=emb_sess_abc123...&state=abc123

app.get('/callback', async (req, res) => {
  const { result_token, session_id, state } = req.query

  // Verify CSRF state
  const expectedState = getStoredState(session_id)
  if (state !== expectedState) {
    return res.status(403).send('State mismatch')
  }

  // Validate the token (next step)
})

const validation = await fetch(
  'https://app.emblemapp.com/api/v1/verify/validate',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.EMBLEM_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ result_token }),
  }
)

const result = await validation.json()

{
  "valid": true,
  "verified": true,
  "level": "L1",
  "challenge_age": 25,
  "session_id": "emb_sess_abc123...",
  "integration_id": "a1b2c3d4-...",
  "validated_at": "2026-01-01T00:05:00.000Z"
}

Important constraints

Optional recovery: reconcile a session

If you need a pull-based fallback for recovery or debugging, you can query the final state of a specific session:

const reconciliation = await fetch(
  `https://app.emblemapp.com/api/v1/verify/sessions/emb_sess_abc123`,
  {
    headers: {
      Authorization: `Bearer ${process.env.EMBLEM_SECRET_KEY}`,
    },
  }
)

const session = await reconciliation.json()

This endpoint is useful for reconciliation and operational recovery. It is not a replacement for webhooks, and it is not a replacement for POST /api/v1/verify/validate.

In production, this endpoint is rate limited for recovery use cases and returns 429 with a Retry-After header when limits are exceeded.

Example response:

{
  "session_id": "emb_sess_abc123",
  "status": "FAILED",
  "verified": false,
  "failure_code": "PROVIDER_REJECTED",
  "failure_reason": "Verification was rejected by the provider",
  "level": "L1",
  "challenge_age": 25,
  "completed_at": "2026-01-01T00:05:00.000Z",
  "expires_at": "2026-01-01T00:10:00.000Z",
  "result_available": false
}

Error handling

All error responses follow a consistent envelope:

{
  "error": "Human-readable message",
  "error_code": "MACHINE_READABLE_CODE",
  "message": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "details": ["Optional validation details"],
  "request_id": "req_...",
  "correlation_id": "corr_..."
}

error_code mirrors code, and message mirrors error. Log request_id and correlation_id when contacting support.

Errors — POST /api/v1/verify/start

Errors — POST /api/v1/verify/validate

For the JavaScript SDK, use the full SDK Reference. It covers server and browser client setup, browser-only /verify/start, server-only validation, error handling, and webhook verification.

Security checklist

Before going to production, verify these are in place:

• Store and verify state — generate a random CSRF token, store it in your session, and reject callbacks where state doesn't match
• Validate immediately — result tokens expire in 5 minutes. Call /validate as soon as you receive the callback.
• Cache the validation result — tokens are single-use. Store the response in your session so you can reference verification status without re-validating.
• Keep your secret key server-side — never expose emb_sk_... in client-side code. Use emb_pk_... for browser calls.
• Use HTTPS for callback URLs — Emblem rejects HTTP callbacks in production.
• Handle webhooks — use webhook events to monitor completed, failed, and expired sessions.

Language support

Emblem supports six UI languages: en (English), de (German), es (Spanish), fr (French), pt (Brazilian Portuguese), and it (Italian).

To control the language shown to users, pass an optional language field when starting a session:

const { redirect_url } = await fetch(
  'https://app.emblemapp.com/api/v1/verify/start',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.EMBLEM_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      integration_id: process.env.EMBLEM_INTEGRATION_ID,
      callback_url: 'https://your-site.com/callback',
      language: 'pt', // Brazilian Portuguese
    }),
  }
)

res.redirect(redirect_url)
// redirect_url will include lang=pt, applied to both the Emblem UI
// and the downstream provider verification UI

Resolution order (highest to lowest priority):

1. language field in the /start request
2. User's previous language selection (browser session storage)
3. Browser Accept-Language / navigator.languages
4. Default: en

Locale variants (pt-BR, de-DE, es_419, it-IT) are normalized to the base code. Unsupported values are silently ignored.

Provider face matching

For supported SafePassage and PrivateAV flows, provider face matching behavior is configured on the Integration in the Emblem dashboard. Use separate integrations for jurisdiction-specific flows, such as a standard integration and an Italy integration with face matching disabled.

This setting controls provider execution behavior only. It does not change Emblem Pass semantics, L1/L2 verification level, pass creation, or reuse eligibility.

Complete Express example

Here's a minimal but complete Express server implementing the full flow:

import 'dotenv/config'
import express from 'express'
import crypto from 'node:crypto'

const app = express()
const sessions = new Map()

const EMBLEM_URL = 'https://app.emblemapp.com'
const CALLBACK_URL = `${process.env.APP_BASE_URL}/callback`

// Start verification
app.post('/verify', async (req, res) => {
  const state = crypto.randomBytes(16).toString('hex')

  const response = await fetch(`${EMBLEM_URL}/api/v1/verify/start`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.EMBLEM_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      integration_id: process.env.EMBLEM_INTEGRATION_ID,
      callback_url: CALLBACK_URL,
      state,
    }),
  })

  if (!response.ok) {
    const error = await response.json()
    return res.status(response.status).json({ error: error.code })
  }

  const { session_id, redirect_url } = await response.json()
  sessions.set(session_id, { state })
  res.redirect(redirect_url)
})

// Handle callback
app.get('/callback', async (req, res) => {
  const { result_token, session_id, state } = req.query

  if (typeof result_token !== 'string' || !result_token) {
    return res.status(400).send('Missing result_token')
  }

  const session = sessions.get(session_id)

  if (!session || state !== session.state) {
    return res.status(403).send('Invalid session or state mismatch')
  }

  const validation = await fetch(`${EMBLEM_URL}/api/v1/verify/validate`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.EMBLEM_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ result_token }),
  })

  if (!validation.ok) {
    const error = await validation.json()
    return res.status(validation.status).json({ error: error.code })
  }

  const result = await validation.json()

  // Grant access — user is verified at the returned level
  res.send(
    `Verified at ${result.level}! (provider threshold: ${result.challenge_age})`
  )
})

app.listen(3000)

Test locally with ngrok

Emblem requires HTTPS for callback URLs in production. During development, use ngrok to create a public HTTPS tunnel to your local server:

# Start your server
node server.mjs

# In another terminal, create an HTTPS tunnel
ngrok http 3000

Use the ngrok HTTPS URL (e.g., https://abc123.ngrok-free.app) as your callback_url when starting verification sessions.

Next steps

• SDK Reference — Full SDK documentation with error handling and webhook verification
• Webhooks — Receive server-to-server notifications for all verification events
• API Reference — Full request/response schemas