v1.0.3: API Key Authentication Middleware Is Live

Today we're shipping v1.0.3 of Calmony Pay, which lays the security and reliability foundation that every subsequent API feature will build on. Here's what's included.

Bearer token authentication with hashed key storage

All requests to the Calmony Pay API must now be authenticated with a secret API key passed as a Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Keys are stored hashed in the api_keys table — we never store your raw secret. The middleware validates the presented key on every request and resolves the project it belongs to, so downstream handlers always have full context about the caller.

We support two key prefixes out of the box:

sk_live_ — for production traffic against real payment instruments.
sk_test_ — for sandbox testing with no real funds involved.

Per-key rate limiting at 100 req/s

To protect service stability, each API key is limited to 100 requests per second. If your integration exceeds this, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 1

Use the Retry-After header value to implement a simple back-off loop in your client code.

Idempotency keys on all POST endpoints

Network errors happen. Without idempotency, a retry after a timeout could charge a customer twice. Calmony Pay solves this with the Idempotency-Key header on every POST endpoint.

Send a unique key (we recommend UUID v4) with your request:

Idempotency-Key: a8098c1a-f86e-11da-bd1a-00112444be1e

If we receive the same key again within 24 hours, we return the original response from cache rather than re-running the operation. After 24 hours the key expires and the request is treated as new.

This means your retry logic can be simple and aggressive — Calmony Pay handles the deduplication.

What's next

With authentication, rate limiting, and idempotency in place, the next releases will focus on the core payment and invoice endpoints that sit behind this middleware layer. Stay tuned.