API & operations

Server API, webhooks, and data controls

Use these interfaces from trusted backend code. All paths below are relative tohttps://<YOUR_IKYC_HOST>/api/v1.

Authentication boundaries

Server-to-server API

These operations require a trusted server integration. For the Flutter native-session sequence, use the dedicated Flutter guide instead of calling the direct verification endpoints from a mobile client.

Dashboard API

Dashboard operations use a dashboard bearer token and the caller’s organisation/project role. They manage projects, keys, verification records, browser settings, webhooks, and approved compliance workflows. They are not native-mobile SDK endpoints.

Signed webhooks

Configure a webhook URL and signing secret in the project dashboard. Verify the signature over the unmodified raw request body before parsing it. Make your handler idempotent: the same event can be delivered more than once during retry.

import crypto from "node:crypto";

export function verifyIkycSignature(
  secret: string,
  rawBody: string,
  signature: string,
) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex"),
  );
}

Webhook payloads do not replace a controlled status lookup. Keep raw identity data, images, biometric data, provider responses, NINs, BVNs, and tokens out of your webhook logs.

Identity lookup and retention controls

Identity lookup endpoints accept a 64-character HMAC-SHA256 digest, not a raw NIN. Use a dedicated server-side NIN_HMAC_SECRET; do not reuse application token or encryption keys.

import crypto from "node:crypto";

export function computeNinHmac(nin: string) {
  return crypto
    .createHmac("sha256", process.env.NIN_HMAC_SECRET!)
    .update(nin)
    .digest("hex");
}

// Send only this 64-character digest to identity lookup endpoints.
const ninHmac = computeNinHmac("<NIN>");

Use the project’s data-subject and erasure controls for approved privacy requests. Keep only the operational data your organisation is authorized to retain.