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 | Documents are transmitted and reported for real |
sumu_test_ | Sandbox | Documents are built and validated, never transmitted |
Create keys in the dashboard under Settings → API keys. 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.
| Status | Code | Meaning |
|---|---|---|
| 401 | MISSING_API_KEY | No X-API-Key header |
| 401 | INVALID_API_KEY | Key not recognised |
| 401 | REVOKED_API_KEY | Key was revoked |
| 403 | ENVIRONMENT_MISMATCH | 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.