---
title: "Authentication"
description: "Create, scope, store, rotate, and revoke Verify Checkout API keys safely."
canonical_url: "https://checkout.verify.et/docs/authentication"
markdown_url: "https://checkout.verify.et/docs/authentication.md"
last_updated: "2026-10-06"
x_farming_labs_generated_preamble: true
---

# Authentication
URL: /docs/authentication
LLM index: /llms.txt
Description: Create, scope, store, rotate, and revoke Verify Checkout API keys safely.
Related: /docs/dashboard-setup, /docs/integration, /docs/troubleshooting

# Authenticate server requests

Create API keys in [Developer settings](/dashboard/developers). 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.

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

<Callout type="danger" title="Never ship an API key to a client">
  Do not place a key in browser JavaScript, a mobile bundle, a public environment
  variable, source control, analytics, logs, or a hosted checkout URL.
</Callout>

## 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:

```json
{
  "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.

## Sitemap

Sitemap discovery is not enabled for this deployment.