API Key Authentication, Rate Limiting & Idempotency

Introduced in v1.0.3

Calmony Pay uses a middleware layer that runs on every API request to authenticate callers, enforce rate limits, and handle idempotent operations safely.

---

Authentication

Every request must supply a secret API key as a Bearer token in the Authorization header.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Key types

Prefix	Environment	Notes
sk_live_…	Production	Charges real funds
sk_test_…	Sandbox	No real funds moved

The middleware:

1. Extracts the Bearer token from the Authorization header.
2. Validates it against the hashed api_keys table.
3. Resolves and attaches the associated project context to the request for downstream handlers.

Requests with a missing, malformed, or unrecognised key receive a 401 Unauthorized response.

---

Rate Limiting

Each API key is subject to a limit of 100 requests per second.

When a key exceeds this limit the API responds with:

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

The Retry-After value is in seconds. Clients should honour this header and back off before retrying.

Best practices

• Implement exponential back-off when handling 429 responses.
• Spread bursts of requests over time rather than sending them all at once.
• Use separate keys per integration if you need independent rate-limit buckets.

---

Idempotency Keys

All POST endpoints support the Idempotency-Key header, which lets you safely retry a request without risk of duplicate operations (e.g. charging a customer twice).

How it works

1. Include a unique Idempotency-Key value in your POST request header.
2. If a request with that key has already been processed, the original cached response is returned immediately — the operation is not replayed.
3. Cached responses are retained for 24 hours from the time of the first successful request.
4. After 24 hours the key expires; a new request with the same key will be treated as a fresh operation.

POST /v1/payments
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
Idempotency-Key: a8098c1a-f86e-11da-bd1a-00112444be1e
Content-Type: application/json

{ "amount": 2500, "currency": "gbp", "payment_method": "pm_xxx" }

Choosing idempotency key values

• Use a UUID v4 or another high-entropy unique identifier.
• Generate the key client-side before sending the request so you can reuse it on retry.
• Keys are scoped per API key — the same idempotency key value used by two different API keys will not collide.

Responses

Scenario	HTTP status
First request (processed normally)	As per the endpoint (e.g. 200, 201)
Duplicate request within 24 h	Original status code returned from cache
Duplicate request after 24 h	Processed as a new request