Authentication
Authenticate requests using bearer API keys.
API Keys
All requests to the public API must include an Authorization header with a bearer token:
Authorization: Bearer <api-key>API keys are scoped to a team and carry one or more scopes that restrict what they can do. Keys are created in Settings → API Keys in the Parseo dashboard.
Key format
Live keys: parseo_live_<48 base62 characters>
Scopes
| Scope | What it grants |
|---|---|
invoice:read | Read invoice data |
invoice:write | Upload new invoices |
invoice:export | Download exports in an accounting-system format |
client:read | List and inspect clients |
client:write | Create, update, and delete clients |
contact:read | List and inspect contacts |
contact:write | Create, update, and delete contacts |
webhook:read | List and inspect webhook endpoints |
webhook:manage | Create, update, delete, and test webhook endpoints |
audit:read | Query the team audit log |
A key may carry any combination of scopes. The minimum required scope is stated on each endpoint.
Rate limits
All endpoints are rate-limited per API key. The default limits are:
| Window | Limit |
|---|---|
| Per minute | 60 requests |
| Per hour | 1 000 requests |
When a limit is exceeded the API returns 429 Too Many Requests with a Retry-After header indicating when the window resets. See Rate Limit Exceeded.
Key rotation
To rotate a key: create a new key in the dashboard, update your integration to use the new key, then delete the old key.
Idempotency keys are scoped per API key. Idempotency keys from the old key do not carry over to the new key. In-flight retries that switch keys mid-loop will be treated as new requests. Drain in-flight requests before switching credentials to avoid duplicate invoices.
Client context
Most endpoints that create or retrieve invoices require an X-Client-Id header identifying which client the operation belongs to. The value is the client's internal ID from the Parseo dashboard.
X-Client-Id: <client-id>