> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centsless.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate with the Centsless API

> Authenticate with the x-api-key header on every request. Keys are role-scoped — merchant, auditor, or partner — with separate rate limits per environment.

Every request to the Centsless API (except `GET /health` and `GET /version`) must include an API key in the `x-api-key` request header. Keys are role-scoped, meaning each key type has a defined set of permissions that matches its intended use — a merchant key can process transactions, but cannot access admin endpoints or audit logs outside its own merchant record.

## Making authenticated requests

Pass your API key in the `x-api-key` header on every request:

```bash theme={null}
curl -X POST https://api.centsless.org/api/v1/transaction \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "merchant_id": "MERCHANT-001",
    "subtotal_cents": 523,
    "tax_total_cents": 200,
    "payment_method": "cash",
    "state": "AZ"
  }'
```

## Key types

| Key type | Prefix               | Permissions                           | Use case               |
| -------- | -------------------- | ------------------------------------- | ---------------------- |
| Merchant | `centsless_`         | Transactions, receipts, tips, exports | POS integration        |
| Auditor  | `centsless_`         | Read-only audit logs, compliance data | Compliance review      |
| Admin    | (custom)             | Full platform access                  | Platform management    |
| Partner  | `centsless_partner_` | Merchant onboarding, scoped access    | POS vendor integration |

As a POS vendor, you will typically use a **Partner** key (`centsless_partner_`) to onboard merchants, and issue **Merchant** keys to each merchant location for transaction processing.

## Key security

* API keys are hashed with SHA-256 before storage. Raw keys cannot be retrieved after creation.
* Keys are shown once at creation. Store them securely — Centsless cannot recover a lost key.
* Keys can be revoked immediately through the admin API or admin portal.
* Rate limits are enforced per key: **1,000 requests/hour** in sandbox, **10,000 requests/hour** in production.

<Warning>
  If you lose an API key, you must revoke it and generate a new one. Centsless has no way to show you a key again after creation.
</Warning>

## Error responses

If the `x-api-key` header is missing or the key is invalid, the API returns a `401` status:

```json theme={null}
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

If the key is valid but does not have permission for the requested endpoint, the API returns a `403` status:

```json theme={null}
{
  "error": "FORBIDDEN",
  "message": "Insufficient permissions for this endpoint"
}
```