Authentication
Every API request authenticates with an API key sent as a Bearer token. Keys are scoped to your organization and can be restricted to a subset of endpoints.
Bearer token
Send the key in the Authorization header, prefixed with Bearer. Live keys start with psk_live_, sandbox keys with psk_test_. The key is shown exactly once at creation — keep it in a secret manager, never in source or version control.
Authorization: Bearer psk_live_3f9a...Per-key allowlists
Each key carries an allowlist that limits which endpoints it can call. A key without the required scope gets a 403 forbidden. Issue least-privilege keys per integration and rotate them from the dashboard if one is ever exposed.
Rate limits
Responses carry X-RateLimit-* headers describing the current window. When you exceed the limit you get a 429 rate_limited together with a Retry-After header. Honour it and retry with exponential backoff.
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum number of requests allowed in the current window. |
X-RateLimit-Remaining | How many requests you have left in the current window. |
X-RateLimit-Reset | Unix timestamp at which the window resets. |
Retry-After | Seconds to wait before retrying (present on 429 only). |
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718700000
Retry-After: 12
Content-Type: application/json
{
"code": "rate_limited",
"message": "You exceeded the per-minute request rate.",
"request_id": "req_01J9Z8H..."
}Idempotency-Key
For POST requests you can send an Idempotency-Key header (a UUID) to make retries safe against double processing. Replaying the same key with a different body returns 409 idempotency_conflict; the same key with the same body returns the original response.
curl -X POST https://api.posty.ro/v1/addresses/verify \
-H "Authorization: Bearer psk_live_xxx" \
-H "Idempotency-Key: 7c1f6e2a-9b3d-4e6f-8a1c-2d4f6e8a0b2c" \
-H "Content-Type: application/json" \
-d '{ "freeform": "Str. Mihai Viteazu 12, Cluj" }'