Authentication

Every request to the VerifAi API is authenticated with a secret API key sent as a bearer token. Keys are managed entirely by you, in your dashboard.

API keys

Create, name and revoke keys on the API keys page. A key is shown in full once, at creation; afterwards only its prefix (for example vk_live_8213…) is ever displayed. Store it securely and treat it like a password — anyone with the key can spend your credits. Revoking a key takes effect immediately: the very next request made with it is rejected.

Sending your key

Put the key in an Authorization header using the Bearer scheme:

Authorization: Bearer vk_live_8213890946054a8497b9c53ba1430fb3

A missing, malformed or revoked key returns 401 with the standard error envelope:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing, malformed, revoked, or expired.",
    "doc_url": "https://ratifai.app/docs-errors.html#invalid_api_key"
  },
  "request_id": "req_1785953541427"
}

A key that has been revoked returns 401 with code revoked_api_key. Your tenant is resolved from the key alone — you never pass an account or tenant id, and any tenant_id you put in a request body is ignored.

Rate limits

Requests are rate limited per API key, per minute. The ceiling depends on your plan:

Exceed the limit and the request is rejected with 429 and a Retry-After header (in seconds) telling you when to try again:

HTTP/1.1 429
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "You are sending requests faster than your plan allows.",
    "doc_url": "https://ratifai.app/docs-errors.html#rate_limited"
  },
  "request_id": "req_…"
}

Idempotency & safe retries

To make a write safe to retry, attach an idempotency key. You can send it either as a body field or as a header:

• Body field: "idempotency_key": "your-unique-value"
• Header: Idempotency-Key: your-unique-value

If both are present, the header wins. When VerifAi sees an idempotency key it has already processed for your tenant, it returns the original stored response and does not charge again — so a network retry can never double-bill or double-count. Use a fresh key for each distinct request (a UUID works well).

Idempotency keys are scoped to your tenant. Reusing a key returns the first response verbatim, including its original request_id.