Agent integration guide

A safe, deterministic contract for coding agents integrating VOVE ID.

Use this page with the canonical llms.txt and the human-readable endpoint guides.

Non-negotiable boundaries

• Keep x-api-key and webhook signing secrets on a trusted server.

• Give clients only the matching public key and a short-lived, subject-scoped session token.

• Use Sandbox (.net API and hosted flow) until Production is approved.

• Generate a stable refId before session or case creation and reuse it for reconciliation.

• Verify Svix over raw request bytes, deduplicate using svix-id, return 2xx quickly, and process asynchronously.

• Treat SDK and redirect results as journey signals. Retrieve the API resource before a final decision.

• Preserve unknown statuses and route them to safe review.

• Log identifiers and outcomes, never secrets, tokens, raw payloads, documents, biometrics, or unredacted personal data.

Minimal KYC workflow

1. The backend persists a stable refId.

2. The backend calls POST https://api.voveid.net/v2/sessions with x-api-key.

3. The backend returns only the token and matching Sandbox public key to the intended client.

4. The client initializes its platform SDK with the sandbox environment and starts the journey.

5. The backend verifies and deduplicates the webhook.

6. An asynchronous worker retrieves GET https://api.voveid.net/v2/users/{refId}.

7. The application applies its policy to the current server-side status.

Contract rules agents commonly miss

• KYC endpoints use /v2; KYB and AML endpoints do not.

• KYB case creation accepts only refId and optional flow. Pass flow for a specific country flow; omit it to let the applicant choose the business country.

• React Native cancellation is cancelled at runtime; use the exported enum.

• AML NO_MATCH describes the configured search, not universal clearance.

• A webhook event can be duplicated or arrive out of order.

• A success callback or redirect is not sufficient evidence for a final server-side decision.

Idempotency and retries

Use refId as the business correlation key and svix-id as the webhook delivery key. If a create request times out, query or otherwise reconcile the stable reference before issuing another create.

Retry idempotent reads with bounded exponential backoff and jitter. Do not retry a validation failure unchanged.

Code-generation checklist

Generated integrations should include:

• environment variables for API origin, private key, public key, and webhook secret;

• a backend-only session endpoint;

• an SDK or hosted-flow client;

• a raw-body webhook route;

• event deduplication before side effects;

• current-resource retrieval after the webhook;

• explicit handling of every documented status plus an unknown fallback;

• tests for expired tokens, invalid signatures, duplicate delivery, cancellation, pending review, and environment mismatch.

Generated examples must use fictional identifiers and placeholder credentials. They must not encode a customer-specific policy as a VOVE ID platform guarantee.

Production boundary

An agent can prepare code and tests, but a human owner must approve credentials, allowed domains, flow configuration, compliance policy, webhook infrastructure, rollback behavior, and the Production release. Use the production checklist.