Client Scoping

Parseo organizes invoices under clients (your end-customers). Every invoice belongs to exactly one client. All public API requests that create or read invoices require client context.

Two Approaches

Pattern A — Team-Scoped Key

A single API key for your team. You specify which client to target per request using the X-Client-Id header.

curl -X POST https://api.parseo.app/external/v1/invoices \
  -H "Authorization: Bearer parseo_live_..." \
  -H "X-Client-Id: cl_9Z8y7X..." \
  -F "file=@invoice.pdf"

Use this when you have multiple clients and one integration handles all of them.

Pattern B — Client-Scoped Key

A key bound to a single client at creation time. No X-Client-Id header needed — the client is implicit.

curl -X POST https://api.parseo.app/external/v1/invoices \
  -H "Authorization: Bearer parseo_live_..." \
  -F "file=@invoice.pdf"

Use this for white-label or embedded integrations where each end-customer gets their own API key.

Client ID Format

Client IDs use the cl_ prefix: cl_5F4e3D2c1B0a9Z8y7X6w5V. Find client IDs in the Parseo dashboard under Settings → Clients.

Header Mismatch

If a client-scoped key is used with an X-Client-Id header pointing to a different client, Parseo returns 403 client.mismatch. This is a hard error, not a silent coercion — it surfaces bugs early in development.

List Scoping

GET /invoices is always scoped to the resolved client context. A team-scoped key with X-Client-Id returns only that client's invoices. A client-scoped key returns only its bound client's invoices, regardless of any clientId filter in the query string.