Authenticate with the Centsless API

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 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.

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"
}

Get Started

Core Concepts

Guides

Authenticate with the Centsless API

Making authenticated requests

Key types

Key security

Error responses

​Making authenticated requests

​Key types

​Key security

​Error responses

Making authenticated requests

Key types

Key security

Error responses