Authenticate server requests

Create API keys in Developer settings. A secret begins with vchk_ and is displayed once. Store it immediately in your server's secret manager; only a non-secret fingerprint remains visible in the dashboard.

Authorization: Bearer vchk_replace_with_your_secret
VerifyCheckout-Version: 2026-06-01

Key scopes

Grant only the actions a service performs. A deposit integration typically needs permission to create deposits and to read deposits or events for reconciliation. A key without the required scope receives 403 even when the secret is valid.

Version and idempotency headers

Send VerifyCheckout-Version: 2026-06-01 so your integration keeps an explicit contract. The header is currently optional, but pinning it is recommended.

Every POST /v1/deposits request requires Idempotency-Key. Reuse the same value only when retrying the same logical deposit; use a new value for a new deposit.

Rotation and revocation

1. Create a replacement key with the same minimum scopes.
2. Deploy the replacement secret to every server that needs it.
3. Confirm requests succeed with the new key.
4. Revoke the old key in the dashboard.

Revocation is immediate. Keep key ownership and last-used information in your operational review so unused credentials do not linger.

Errors and request correlation

Authentication failures use the same stable envelope as other API errors:

{
  "data": null,
  "error": {
    "code": "unauthorized",
    "message": "Authentication is required"
  },
  "meta": {
    "requestId": "req_example"
  }
}

Record meta.requestId with the failed operation. It lets support correlate your report without sharing secrets or authorization headers.