Skip to main content
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: 
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 typePrefixPermissionsUse case
Merchantcentsless_Transactions, receipts, tips, exportsPOS integration
Auditorcentsless_Read-only audit logs, compliance dataCompliance review
Admin(custom)Full platform accessPlatform management
Partnercentsless_partner_Merchant onboarding, scoped accessPOS 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.
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.

​
Error responses

If the x-api-key header is missing or the key is invalid, the API returns a 401 status: 
{
  "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: 
{
  "error": "FORBIDDEN",
  "message": "Insufficient permissions for this endpoint"
}