Authentication and keys
Bearer keys, scopes, two environments, and how a workspace reaches production.
Send the key as a bearer token: Authorization: Bearer tp_live_… or tp_test_…. TaxPio stores only a hash and the first fourteen characters; a lost key is replaced, never recovered. Keys expire on the schedule chosen at creation (30, 90 or 365 days, or never) and can be revoked at once from the console.
| Scope | Grants |
|---|---|
calculations:read | Read calculations |
calculations:write | Run calculations |
connections:manage | Invite, list and end connections to client profiles |
records:import | Push records into connected profiles |
records:read | Read back the records it pushed |
documents:read | Read documents |
documents:write | Upload documents |
webhooks:manage | Manage webhooks |
usage:read | Read usage and credits |
Environments
A sandbox key (tp_test_…) runs the same rule packages against the same engine, with no path to any government system, and is never billed. A live key (tp_live_…) is minted only after the workspace passes production review: TaxPio reviews the use case, security and filing access before live scopes are enabled. Sandbox-only operations answer 403 SANDBOX_ONLY to a live key; government-facing operations answer 403 LIVE_ONLY to a sandbox key.
Rate limits
| Environment | Requests per minute per key |
|---|---|
live | 600 |
sandbox | 120 |
Every response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset. Over the limit the API answers 429 RATE_LIMITED with retry-after in seconds; the bucket refills continuously.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api.taxpio.com"
{ "error": "The API key is not recognised.", "code": "API_KEY_INVALID", "requestId": "…", "docs_url": "https://docs.taxpio.com/errors#api-key-invalid" }