Authentication

All API requests require a Bearer token in the Authorization header.

Making authenticated requests

Include your API key in every request:

curl -X POST https://api.clevis.dev/v1/payroll/calculate \
  -H "Authorization: Bearer clevis_live_7f3a9c2e4b1d..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

import httpx

response = httpx.post(
    "https://api.clevis.dev/v1/payroll/calculate",
    headers={"Authorization": "Bearer clevis_live_7f3a9c2e4b1d..."},
    json={ ... },
)

const response = await fetch("https://api.clevis.dev/v1/payroll/calculate", {
  method: "POST",
  headers: {
    Authorization: "Bearer clevis_live_7f3a9c2e4b1d...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ ... }),
});

Keep your API key secret. Do not expose it in client-side code, public repositories, or browser-accessible environments.

Key format

clevis_live_7f3a9c2e4b1d...      production
clevis_test_a91c02ee7fd3...      sandbox

Three things worth knowing about that shape: The prefix carries the environment. A sandbox key presented to production is rejected before it touches anything, with 401 API_KEY_WRONG_ENVIRONMENT. This exists to prevent the most expensive mistake this product can cause: running against real payroll while believing you are in sandbox.

Your client is not your key

Every customer has a stable client_id that never rotates. Keys are credentials that prove who you are; they are not the identity itself. This matters in practice. Everything scoped to you — your stored calculations, your payouts, your idempotency keys, your external_id uniqueness — is keyed to the client_id, not to the key you happened to present. Rotating a key does not cost you your history, and it does not let a retry through as a new request.

How keys are stored

Clevis stores only the SHA-256 digest of each key, never the key itself, and compares in constant time. A key is shown once, when it is issued — the same convention as Stripe, GitHub and AWS.

Because only the digest is stored, a lost key cannot be recovered. It can only be rotated.

Authentication errors

Code	HTTP	Description
`MISSING_AUTH_TOKEN`	401	No `Authorization` header provided
`INVALID_API_KEY`	401	The key is unknown or has been revoked
`API_KEY_WRONG_ENVIRONMENT`	401	A sandbox key was used against production, or vice versa

{
  "error": {
    "code": "MISSING_AUTH_TOKEN",
    "message": "Authorization header is required",
    "details": {},
    "request_id": "01HX9B2KM3..."
  }
}

Request ID

Every API response includes a unique request_id (in the response body and the X-Request-ID header). Include this ID, and the key_id if the problem looks like an auth one, when contacting support.

Get Started

Countries

Calculations

Payouts

Guides

Making authenticated requests

Key format

Your client is not your key

How keys are stored

Authentication errors

Request ID

​Making authenticated requests

​Key format

​Your client is not your key

​How keys are stored

​Authentication errors

​Request ID

Making authenticated requests

Key format

Your client is not your key

How keys are stored

Authentication errors

Request ID