> For the complete documentation index, see [llms.txt](https://docs.voveid.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voveid.com/docs/ai-assisted-integration/agent-integration-guide.md).

# Agent integration guide

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

Use this page with the canonical [`llms.txt`](https://docs.voveid.com/docs/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](/docs/production-readiness.md).