> 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/api-fundamentals/api-conventions.md).

# API conventions

Shared VOVE ID API behavior for environments, authentication, identifiers, responses, and retries.

## Base URLs

| Environment | Base URL                 | Purpose                             |
| ----------- | ------------------------ | ----------------------------------- |
| Sandbox     | `https://api.voveid.net` | Build and test with fictional data  |
| Production  | `https://api.voveid.com` | Process approved production traffic |

KYC routes begin with `/v2`. KYB and AML routes are unversioned. Use the path shown on each endpoint page.

## Authentication

Server-to-server requests use the `x-api-key` header:

```http
x-api-key: vove_sandbox_replace_me
accept: application/json
```

API keys are private credentials. Store them in a server-side secret manager, never in browser code, mobile applications, URLs, analytics, screenshots, or logs.

Client SDKs use a public SDK key plus a short-lived session token created by your backend. Public keys are not substitutes for API keys.

## Stable identifiers

Create and persist a stable `refId` before starting a KYC session, KYB case, or AML case. Use it to correlate your record with webhooks and result retrieval. Do not silently generate a different `refId` after a timeout; reconcile the original request first.

## Request and response format

Unless an endpoint says otherwise:

* Send JSON with `content-type: application/json`.
* Treat documented enum values as case-sensitive.
* Tolerate additive response fields.
* Do not depend on undocumented fields.
* URL-encode all path and query values.

## Errors and retries

Branch first on HTTP status, then on a documented machine-readable error code when present. Retry only when the operation is safe to repeat, using bounded exponential backoff with jitter.

For a timeout on a create operation, assume the result is unknown. Query by the stable identifier before attempting another create.

See [Errors](/docs/api-fundamentals/errors.md) for recovery guidance.