Integration Guide — espuni

npm install @espuni/node

import { EspuniClient } from '@espuni/node';

const client = new EspuniClient({
  clientId:     process.env.ESPUNI_CLIENT_ID,
  clientSecret: process.env.ESPUNI_CLIENT_SECRET,
});

// 1. Create a verification session
const { sessionId, crossDeviceUri } = await client.createSession({
  webhookUrl: 'https://your-app.com/webhooks/av',
});
// Render crossDeviceUri as a QR code for the user

// 2. Receive the result (webhook — Express example)
app.post('/webhooks/av', express.json(), (req, res) => {
  const event = client.parseWebhookPayload(req.body);
  // event.verified → true | false
  // event.claims   → { age_over_18: true }
  res.sendStatus(200);
});

// 3. Or poll session status
const result = await client.getSession(sessionId);
// result.status  → 'pending' | 'completed' | 'failed' | 'expired'
// result.claims  → { age_over_18: true }

{
  "credentials": {
    "clientId": "cp-a1b2c3d4",
    "clientSecret": "...",
    "tokenEndpoint": "https://api.espuni.com/api/oauth2/token",
    "apiUrl": "https://api.espuni.com"
  }
}

POST /api/oauth2/token
Authorization: Basic base64(clientId:clientSecret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

POST /api/oauth2/token
Content-Type: application/json

{ "client_id": "cp-a1b2c3d4", "client_secret": "..." }

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 86400
}

POST /api/verifier/offer
Authorization: Bearer <token>

{
  "requestId": "age-verification-sandbox",
  "response_type": "uri",
  "webhook": { "url": "https://tu-app.com/webhook", "auth": { "type": "none" } }
}

POST /api/verifier/offer
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "requestId": "age-verification",
  "response_type": "uri",
  "webhook": {
    "url": "https://your-server.com/webhooks/av",
    "auth": { "type": "none" }
  }
}

{
  "session": "abc123",
  "uri": "openid4vp://...",
  "crossDeviceUri": "https://eudiplo.espuni.com/vp/..."
}

POST /api/verifier/offer
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "requestId": "age-verification",
  "response_type": "iso-18013-7",
  "webhook": {
    "url": "https://your-server.com/webhooks/av",
    "auth": { "type": "none" }
  }
}

{
  "session": "abc123",
  "uri": "av://...",
  "org_iso_mdoc": {
    "device_request": "o2d...",
    "encryption_info": "g2R..."
  }
}

// ISO 18013-7 DC API flow — browser-native, no QR
const session = await client.createSession({
  responseType: 'iso-18013-7',
  webhookUrl: 'https://your-app.com/webhooks/av',
});
// session.orgIsoMdoc = { deviceRequest, encryptionInfo }
// Pass these to the browser to drive navigator.credentials.get({ digital: {...} })

// Your frontend POSTs the HPKE-encrypted result to your backend:
app.post('/verify/dc-response/:id', async (req, res) => {
  // Forwards the encrypted wallet response to espuni for decryption + verification
  await client.submitDcResponse(req.params.id, req.body.data, req.body.protocol);
  res.json({ ok: true });
  // Result arrives at your webhook (same as QR flow)
});

// 1. Get the org-iso-mdoc data from your backend
const session = await fetch('/start-verification', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ dcApi: true }),
}).then(r => r.json());
// session.presentationRequest.dc_api.org_iso_mdoc = { device_request, encryption_info }

// 2. Invoke the Digital Credentials API (ISO 18013-7 Annex C)
const result = await navigator.credentials.get({
  digital: {
    requests: [{
      protocol: 'org-iso-mdoc',
      data: session.presentationRequest.dc_api.org_iso_mdoc,
    }]
  }
});
// result.data is the HPKE-encrypted CBOR EncryptedResponse — forward it to your backend

// 3. Forward to your backend for proxying to espuni
await fetch(session.dcApiResponseUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ protocol: 'org-iso-mdoc', data: result.data }),
});
// espuni decrypts and verifies the mDoc — result arrives at your webhook

POST https://your-server.com/webhooks/av
Content-Type: application/json

{
  "session": "abc123",
  "verified": true,
  "claims": {
    "age_over_18": true
  }
}

// Bearer token (recommended)
"auth": { "type": "bearer", "token": "your-secret-token" }

// Custom header
"auth": { "type": "apiKey", "config": { "headerName": "X-Webhook-Secret", "headerValue": "your-secret" } }

// No auth
"auth": { "type": "none" }

GET /api/session/{sessionId}
Authorization: Bearer <access_token>

{
  "sessionId": "abc123",
  "status": "completed",
  "verified": true,
  "claims": {
    "age_over_18": true
  },
  "errorReason": null
}

<script src="https://app.espuni.com/espuni-av.js"></script>

import { EspuniClient } from '@espuni/node';
const client = new EspuniClient({ clientId: process.env.ESPUNI_CLIENT_ID, clientSecret: process.env.ESPUNI_CLIENT_SECRET });

// Create session
app.post('/start-verification', async (req, res) => {
  const useDcApi = req.body.dcApi === true;

  const session = await client.createSession({
    responseType: useDcApi ? 'iso-18013-7' : 'uri',
    webhookUrl: 'https://your-server.com/webhooks/av',
  });

  if (useDcApi) {
    res.json({
      sessionId: session.sessionId,
      presentationRequest: {
        dc_api: { org_iso_mdoc: session.orgIsoMdoc },
      },
      dcApiResponseUrl: `/verify/dc-response/${session.sessionId}`,
    });
  } else {
    res.json({
      sessionId: session.sessionId,
      presentationRequest: {
        oid4vp: {
          qr_url: session.crossDeviceUri,
          events_url: `/verify/events/${session.sessionId}`,
        },
      },
    });
  }
});

// Forward DC API wallet response to espuni
app.post('/verify/dc-response/:id', async (req, res) => {
  await client.submitDcResponse(req.params.id, req.body.data, req.body.protocol);
  res.json({ ok: true });
});

// SSE session status stream
app.get('/verify/events/:id', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  const poll = setInterval(async () => {
    const token = await getAccessToken();
    const s = await fetch(
      `https://api.espuni.com/api/session/${req.params.id}`,
      { headers: { Authorization: `Bearer ${token}` } }
    ).then(r => r.json());
    res.write(`data: ${JSON.stringify(s)}\n\n`);
    if (['completed','failed','expired'].includes(s.status)) {
      clearInterval(poll); res.end();
    }
  }, 1000);
  req.on('close', () => clearInterval(poll));
});

<div id="qr-container"></div>

<script src="https://app.espuni.com/espuni-av.js"></script>
<script>
async function startVerification() {
  const useDcApi = espuni.hasDcApi();

  const session = await fetch('/start-verification', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ dcApi: useDcApi }),
  }).then(r => r.json());

  espuni.verify({
    sessionId: session.sessionId,
    presentationRequest: session.presentationRequest,
    dcApiResponseUrl: session.dcApiResponseUrl,
    container: document.getElementById('qr-container'),
    onSuccess: function(result) {
      // QR: result.claims = { age_over_18: true }
      // DC API: result = { ok: true } — claims arrive at your webhook
      showVerifiedUI();
    },
    onFailure: function(reason) {
      console.error('Failed:', reason);
    },
  });
}
</script>

403 Forbidden
{
  "message": "Monthly verification limit reached (100/100). Upgrade your plan to continue."
}

# 1. Token
TOKEN=$(curl -s -X POST https://api.espuni.com/api/oauth2/token \
  -H "Authorization: Basic $(echo -n 'cp-a1b2c3d4:your-secret' | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=client_credentials' | jq -r .access_token)

# 2. Create offer
OFFER=$(curl -s -X POST https://api.espuni.com/api/verifier/offer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "age-verification",
    "response_type": "uri",
    "webhook": { "url": "https://webhook.site/your-id", "auth": { "type": "none" } }
  }')

SESSION=$(echo $OFFER | jq -r .session)
QR_URL=$(echo $OFFER | jq -r .crossDeviceUri)

echo "Session: $SESSION"
echo "QR URL:  $QR_URL"

# 3. Poll status
curl -s https://api.espuni.com/api/session/$SESSION \
  -H "Authorization: Bearer $TOKEN" | jq .