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

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.company.com/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.company.com/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.company.com/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.

Configuration Endpoints

GET

/api/check-config

No Auth Required

Checks if the v2client instance is properly configured with API keys.

Response (Configured)

{ "configured": true, "baseUrl": "https://backend.okid.io", "hasApiKey": true }

Response (Not Configured)

{ "configured": false, "baseUrl": null, "hasApiKey": false }

POST

/api/test-connection

Admin Only

Tests connectivity to the okID backend with provided configuration.

Admin Use Only

This endpoint is used during admin configuration setup and is not needed for normal operator integration.

Error Responses

Common Error Codes

400Bad Request - Invalid parameters

401Unauthorized - Invalid API key

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
• 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