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.stage.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

Request Body (Optional)

{ "extra_data": { "reference_id": "ABC123", "user_id": "user_456", "custom_field": "any value" }, "return_url": "https://your-app.com/verification-complete" }

Response

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

Extra Data

The optional extra_data field allows you to attach custom metadata to a verification. This data is stored with the verification and returned in webhook notifications, enabling you to track verifications with your internal identifiers (order IDs, user references, etc.).

Return URL

The optional return_url parameter specifies a URL where the user will be automatically redirected after completing verification. When provided:

User sees verification result (success or manual review)
A 3-second countdown is displayed
User is automatically redirected to the specified URL

This is useful for integrations where you want to bring users back to your application after verification completes.

Basic Example

// Server-side only! const response = await fetch('https://verify.stage.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.stage.okid.io/verify?verification_id=${verificationId}`; res.redirect(verifyUrl);

With Extra Data

// Server-side with custom metadata const response = await fetch('https://verify.stage.okid.io/api/generate-verification', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-SDK-Key': process.env.API_KEY }, body: JSON.stringify({ extra_data: { reference_id: 'ORDER-12345', user_id: 'user_789', department: 'onboarding', session_context: 'mobile_app_v2' } }) }); const { verificationId } = await response.json(); // The extra_data will be included in webhook notifications // allowing you to match verifications with your internal systems

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.stage.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.stage.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

Note: These endpoints return the final accepted images from completed verifications. To inspect individual submission attempts (including rejected ones), use the Dashboard.

curl Command Builder

Verification ID

API Key (X-SDK-Key)

Image Type

Environment

Generated curl Command

curl -H "X-SDK-Key: YOUR_API_KEY" "https://verify.stage.okid.io/api/get-verification-image-front/YOUR_VERIFICATION_ID" -o "front.jpg"

Tip: The command will save the image to front.jpg in your current directory.

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.stage.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.stage.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.stage.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.stage.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

GET

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

X-SDK-Key Required

Retrieves the selfie image from the liveness verification module. Returns the accepted selfie used for face matching. 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

Response

Content-Type: image/jpeg (Binary image data)

Example Usage

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

Quick Test (curl)

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

Note

Returns 404 if the verification did not include a liveness module or if liveness verification was not completed.

Error Responses

HTTP Status Codes

401 - Missing X-SDK-Key header

403 - API key doesn't own this verification

404 - Verification not found OR no accepted image available for requested type

404 - Selfie not available (liveness module not completed)

Parameters Reference

image_type (optional, front/back only)

Type of image to retrieve. If not specified, returns the default processed image.

?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