v2client API

v2client API Reference

Complete reference for the v2client verification portal endpoints. Server-to-server integration with your API key.

v2client Architecture

The v2client is a hosted verification portal with server-side endpoints for operator integration:

Your Server

Calls v2client with API key

v2client Portal

Verification interface + API endpoints

okID Backend

Verification processing engine

Security Model

Your API key is sent via X-SDK-Key header for verification generation. All subsequent user interactions use verification IDs.

Base URL

# Production instance
https://verify.prod.okid.io

# Test instance
https://verify.test.okid.io

Authentication

X-SDK-Key header for verification generation

X-SDK-Key header for verification status retrieval

verification_id for user interactions

No API keys in browser/client code

Core Endpoints

POST

/api/generate-verification

X-SDK-Key Required

Generates a verification ID using your API key. This must be called from your server.

Request Headers

Content-Type: application/json X-SDK-Key: your-api-key-here

Response

{ "verificationId": "ver_abc123...", "expiresAt": "2024-01-01T12:00:00Z", "modules": {...}, "flow": ["terms", "document", "liveness"] }

Example Usage

// Server-side only! const response = await fetch('https://verify.test.okid.io/api/generate-verification', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-SDK-Key': process.env.API_KEY } }); const { verificationId } = await response.json(); // Redirect user to verification portal const verifyUrl = `https://verify.test.okid.io/verify?verification_id=${verificationId}`; res.redirect(verifyUrl);

GET

/verify

No Auth Required

User-facing verification portal. Users complete their verification flow here.

Query Parameters

verification_id=ver_abc123...

User Flow

1. Terms acceptance

2. Document upload

3. Liveness detection

4. Form data collection

5. Verification complete

Example URL

https://verify.test.okid.io/verify?verification_id=ver_abc123...

GET

/generate

Internal Use

Internal route for QR code verification generation. Redirects to verification portal.

Usage

This route is primarily used internally by QR codes. For operator integration, use the POST /api/generate-verification endpoint.

GET

/api/get-verification-details/{verification_id}

X-SDK-Key Required

Retrieves the complete verification record including status, results, and metadata. API key must own the verification.

Request Headers

X-SDK-Key: your-api-key-here

Response

{ "verification_id": "ver_abc123...", "status": { "current": "verified", "updated_at": "2024-01-01T12:00:00Z", "progress": { "document": "completed", "liveness": "completed", "form_data": "completed" } }, "results": { "document": {...}, "liveness": {...}, "form_data": {...} } }

Example Usage

// Server-side only! const response = await fetch(`https://verify.test.okid.io/api/get-verification-details/${verificationId}`, { method: 'GET', headers: { 'X-SDK-Key': process.env.API_KEY } }); if (response.status === 403) { console.error('API key does not have access to this verification'); return; } const verificationData = await response.json(); console.log('Verification status:', verificationData.status.current);

Security Note

API keys can only retrieve verifications they created. Attempting to access another organization's verification will result in a 403 Forbidden error.

Image Retrieval Endpoints

GET

/api/get-verification-image/{verification_id}

X-SDK-Key Required

Retrieves the document image with redaction based on API key settings (MRZ, portrait, template fields). X-SDK-Key header is mandatory - requests without this header will be rejected with 401 Unauthorized.

Request Headers

X-SDK-Key: your-api-key-here

Query Parameters (Optional)

attempt_index=0 image_type=original

Example Usage

// Server-side only! const response = await fetch(`https://verify.test.okid.io/api/get-verification-image/${verificationId}?attempt_index=0`, { method: 'GET', headers: { 'X-SDK-Key': process.env.API_KEY } }); if (response.ok) { const imageBlob = await response.blob(); // Process the redacted image (based on API key settings) }

Redaction Settings

The redaction applied depends on your API key configuration: redact_mrz, redact_portrait, and redact_template flags control what information is blacked out.

GET

/api/get-verification-image-unredacted/{verification_id}

X-SDK-Key Required

Retrieves the original document image with only a watermark, ignoring API key redaction settings. X-SDK-Key header is mandatory - requests without this header will be rejected with 401 Unauthorized.

Request Headers

X-SDK-Key: your-api-key-here

Query Parameters (Optional)

attempt_index=0 image_type=original

Example Usage

// Server-side only! const response = await fetch(`https://verify.test.okid.io/api/get-verification-image-unredacted/${verificationId}`, { method: 'GET', headers: { 'X-SDK-Key': process.env.API_KEY } }); if (response.ok) { const imageBlob = await response.blob(); // Process the unredacted image (watermark only) }

Security Note

This endpoint now requires valid API key authentication. The API key must have access to the verification_id being requested.

GET

/api/get-verification-image-front/{verification_id}

X-SDK-Key Required

Directly retrieves the front document image without needing to determine attempt indices. Automatically finds the accepted front image and applies redaction based on API key settings. X-SDK-Key header is mandatory - requests without this header will be rejected with 401 Unauthorized.

Request Headers

X-SDK-Key: your-api-key-here

Query Parameters (Optional)

image_type=original image_type=cropped

Example Usage

// Server-side only! const response = await fetch(`https://verify.test.okid.io/api/get-verification-image-front/${verificationId}?image_type=original`, { method: 'GET', headers: { 'X-SDK-Key': process.env.API_KEY } }); if (response.ok) { const imageBlob = await response.blob(); // Process the front document image (based on API key settings) }

Quick Test (curl)

curl -H "X-SDK-Key: your-api-key-here" https://verify.test.okid.io/api/get-verification-image-front/ver_123 --output front.jpg

Advantages

No attempt index required - automatically finds the accepted front image
Side-specific - explicitly get front document without guessing
Authenticated - secure access control with API key verification
Cleaner API - more intuitive for document-based workflows

GET

/api/get-verification-image-back/{verification_id}

X-SDK-Key Required

Directly retrieves the back document image without needing to determine attempt indices. Automatically finds the accepted back image and applies redaction based on API key settings. X-SDK-Key header is mandatory - requests without this header will be rejected with 401 Unauthorized.

Request Headers

X-SDK-Key: your-api-key-here

Query Parameters (Optional)

image_type=original image_type=cropped

Example Usage

// Server-side only! const response = await fetch(`https://verify.test.okid.io/api/get-verification-image-back/${verificationId}?image_type=original`, { method: 'GET', headers: { 'X-SDK-Key': process.env.API_KEY } }); if (response.ok) { const imageBlob = await response.blob(); // Process the back document image (based on API key settings) }

Quick Test (curl)

curl -H "X-SDK-Key: your-api-key-here" https://verify.test.okid.io/api/get-verification-image-back/ver_123 --output back.jpg

Advantages

No attempt index required - automatically finds the accepted back image
Side-specific - explicitly get back document without guessing
Authenticated - secure access control with API key verification
Cleaner API - more intuitive for document-based workflows

Error Responses (Front/Back Endpoints)

HTTP Status Codes

401 - Missing X-SDK-Key header

403 - API key doesn't own this verification

404 - Verification not found OR no accepted front/back image available

404 - Requested image_type variant not found

Parameters Reference

attempt_index (optional)

Zero-based index of the document upload attempt. Defaults to 0 (first/latest attempt).

?attempt_index=0 # First attempt ?attempt_index=1 # Second attempt

image_type (optional)

Type of image to retrieve. If not specified, uses the stored image path from the attempt.

?image_type=original # Original uploaded image ?image_type=cropped # Cropped/processed image

Error Responses

Common Error Codes

400Bad Request - Invalid parameters

401Unauthorized - Invalid API key

403Forbidden - API key cannot access verification

404Not Found - Invalid verification ID

500Server Error - Internal error

Error Response Format

{ "error": "Invalid API key provided", "details": "The X-SDK-Key header contains an invalid or inactive API key" }

Common Integration Issues

• INVALID_API_KEY - API key not found or inactive
• ACCESS_DENIED - API key cannot access this verification
• SERVER_NOT_CONFIGURED - v2client missing base URL configuration
• VERIFICATION_EXPIRED - verification_id has expired
• VERIFICATION_NOT_FOUND - Invalid verification_id

Rate Limits & Best Practices

Rate Limits

Verification Generation100/minute

Configuration Checks300/minute

Portal AccessNo limit

Best Practices

Store API keys securely on server

Generate verification IDs on-demand

Handle verification expiry gracefully

Use HTTPS for all requests

Next Steps

Integration Guide

Step-by-step integration walkthrough

Verification Modules

Configure verification requirements

Dashboard Guide

Manage API keys and view results