Authentication
One API key per organisation, and the access-control gap that comes with it.
Pass your key in the X-API-Key header on every request. Keys belong to your organisation, not to a
single taxpayer — one key sends on behalf of every taxpayer you have onboarded.
curl https://api.joinsumu.com/v1/api/health \
-H "X-API-Key: sumu_live_7f4a2c9e8b1d6a3f5c0e9d2b8a4f7c1e"Key format
| Prefix | Environment | Behaviour |
|---|---|---|
sumu_live_ | Production | Full rate limits (600/min, 100k/day). Only usable against the production host |
sumu_test_ | Sandbox | Reduced rate limits (120/min, 5k/day). Only usable against a non-production host |
Not a simulation mode
Schematron validation, UBL generation, and AS4/SMP calls are not gated on which key type you use — see Sandbox for the full picture. The two rows above are the differences between environments, not "test keys are harmless."
The key is shown once at creation and stored only as a hash, so it can't be recovered — issue a new one and revoke the old one if it's lost. Several keys can be active at once, which is how you rotate without downtime: create the new key, deploy it, then revoke the old one.
No dashboard exists for this yet
There is no Settings → API keys page today. The backend endpoint that creates an organisation and mints its keys is real (session-authenticated, staff-only), but nothing in the SUMU dashboard calls it — see the roadmap. Provisioning a new integrator currently means a SUMU engineer calling that endpoint directly, not something you can do yourself yet.
Every error on this API — including all of the ones below — comes back as one of a small set of generic
codes, not a granular one per failure reason. Missing, invalid, and revoked keys are all the same
401 UNAUTHORIZED_ERROR; the distinction is only in the message text, not the code. Branch on
error_code plus HTTP status, and read message for the human-readable detail — see
Errors.
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED_ERROR | Missing, unrecognised, or revoked X-API-Key — see message for which |
| 403 | FORBIDDEN_ERROR | Test key used against production, or the reverse |
Access control — current limitation
Today's design is all-or-nothing per organisation key: one key has full access to every taxpayer you've onboarded. For the Platform track especially, that means a leaked key exposes every business under it, and there's no way to hand a staff member or downstream customer their own restricted credentials. This is a known, open gap — see the roadmap — not something to design around as if it's solved.