SDK Reference

verifyIdentity()

Confirm a user's Nigerian ID and receive a SignedCredential bundle. The credential lives in browser memory only - pass it straight to generateProof().

Signature

verifyIdentity(options: VerifyOptions): Promise<SignedCredential>

Parameters

Name	Type	Required	Description
idType	'NIN' \| 'BVN'	required	Which Nigerian ID to verify against.
idNumber	string	required	The 11-digit NIN or BVN. Whitespace and dashes are stripped automatically.
dob	string	required	Date of birth in YYYY-MM-DD format.
backendUrl	string	optional	Override the default verification service URL. Useful for custom configurations.

Returns

A SignedCredential object - a Poseidon-hashed ID plus a cryptographic signature.

SignedCredential

type SignedCredential = {
  idHash: string        // Poseidon hash of ID
  age: number           // computed from dob
  idType: 1 | 2         // 1 = NIN, 2 = BVN
  signature: {
    R8: [string, string]  // Signature point
    S: string             // Signature scalar
  }
  Ax: string            // Public key x coordinate
  Ay: string            // Public key y coordinate
}

What this function does

Validates idType, idNumber format, and dob.
Contacts the Althea verification service with the inputs over HTTPS.
Receives a signed credential confirming the ID.
Returns the SignedCredential to the browser.
The credential lives in memory only - never persisted to disk, localStorage, or any logger.

Errors

Message	Cause	What to do
idType must be NIN or BVN	Invalid idType passed	Fix the input
idNumber must be 11 digits	Wrong length	Validate before calling
dob must be YYYY-MM-DD	Wrong date format	Use ISO format
Verification failed	ID could not be confirmed	Show user-facing error, allow retry
Service unreachable	Network error or service down	Retry with exponential backoff
Too many requests	Request limit exceeded	Wait and retry; surface a clear message

Example

verify-identity-example.ts

import { verifyIdentity, generateProof } from 'afrzk-sdk'

try {
  const credential = await verifyIdentity({
    idType: 'NIN',
    idNumber: '12345678901',
    dob: '2000-01-15',
  })
  // credential is now in memory - pass straight to generateProof()
  const proof = await generateProof(credential)
} catch (error) {
  console.error(error.message)
}

Do not store the credential

Pass the credential directly to generateProof(). If you keep a reference around, the credential lingers in memory until garbage collection.