Authentication

VerifyHQ uses API keys to authenticate requests. Include your key in the X-API-Key header with every request.

Authentication Flow

Create API Client

POST /admin/api-clients

Receive API Key

Store securely (shown once)

Include in Requests

X-API-Key: your_key

Authenticated!

Access granted

Create an API Client

API clients are created via the admin endpoint. You need the admin secret to perform this operation.

POST/admin/api-clients

Create a new API client and receive an API key.

Headers

Parameter	Type	Description
`X-Admin-Secret`required	string	Admin secret for privileged operations
`Content-Type`required	string	application/json

Request Body

Parameter	Type	Description
`name`required	string	Human-readable name for the API client
`permissions`	string[]	List of permissions to grant (e.g., identity:read, document:write)
`rateLimit`	number	Custom rate limit (requests per minute). Defaults to plan limit.

Response

201 Createdjson

{
  "id": "client_abc123",
  "name": "My App",
  "apiKey": "vhq_live_a1b2c3d4e5f6...",
  "permissions": ["identity:read", "identity:write"],
  "rateLimit": 100,
  "message": "Store the API key securely — it will not be shown again."
}

Using Your API Key

Include the key in every request:

curl https://api.verifyhq.com/v1/verifications/identity/ver_123 \
  -H "X-API-Key: vhq_live_a1b2c3d4e5f6"

Key Format

API keys follow this format:

vhq_live_...   → Production key
vhq_test_...   → Sandbox key

Security Best Practices

Never expose API keys in client-side code or public repositories
Use environment variables to store keys
Rotate keys immediately if compromised
Use the minimum permissions required

Available Permissions

Parameter	Type	Description
`identity:read`	permission	Read identity verification status
`identity:write`	permission	Start and manage identity verifications
`document:read`	permission	Read document verification results
`document:write`	permission	Submit documents for verification
`liveness:read`	permission	Read liveness check results
`liveness:write`	permission	Create and submit liveness checks
`webhook:manage`	permission	Configure and manage webhooks
`cognitive:write`	permission	Use cognitive KYC endpoints