Every /api/v1 request authenticates with an API key, sent as a bearer token or an X-API-Key header. Organization, location, and environment scope come exclusively from the key and cannot be widened by request parameters.
Authorization: Bearer itms_test_... # or X-API-Key: itms_test_...
Key prefixes
| Environment | Prefix | Use |
|---|---|---|
| Sandbox | itms_test_ | Created by organization admins after the workspace and API Access module are enabled. |
| Live | itms_live_ | Issued once live access is enabled for the workspace. See Environments. |
One-time secret reveal
The full secret is shown exactly once at creation — store it in a secret manager and never commit it to source control. Only a key prefix is displayed afterward. If a secret is lost, revoke the key and create a new one.
Scopes
Default key scopes are:
tax:calculate— stateless calculation endpoints.transactions:read— list and fetch transactions.transactions:write— create, void, and refund transactions.
Return-package access uses explicit returns:read and returns:write scopes. These are not default scopes and require the corresponding compliance entitlement and filing-unit authorization. A request outside the key's scopes returns 403 insufficient_scope.
Service-provider credentials add four portfolio scopes. They remain scoped to the enabled provider practice and never grant direct access to an underlying taxpayer organization without an authorized engagement:
provider:clients:read— list clients, locations, and readiness.provider:clients:write— create and update canonical client organizations and locations.provider:return-jobs:read— read durable portfolio return-job output.provider:return-jobs:write— submit portfolio return jobs.
Taxpayer-data calls made with a provider credential also require either the recommended provider-owned external reference in X-ITMS-Client-Ref, or the backward-compatible numeric engagement ID in X-ITMS-Client-Id. See the complete service-provider portfolio guide.
Rotation & revocation
Rotate a key in the Developer Console to revoke the current secret and issue a replacement with the same name, environment, and scopes — the new secret is shown once. Revocation takes effect on the next request. Live-key rotation requires the same authorization as live-key creation.
Identify your integration
Send X-ITMS-Client: application-name/version from server-side integrations. This identifier helps support correlate behavior with an application release and does not alter tax results. Responses include X-ITMS-API-Version as an informational contract revision and X-Request-Id for request-level diagnostics.
During sandbox evaluation, send non-secret X-ITMS-Test-Run-Id and X-ITMS-Test-Case-Id values to correlate a test plan with request logs. The sanitized values are echoed in response headers.
Browser sessions are not accepted
Dashboard login sessions (JWTs) are not accepted on /api/v1. API keys cannot read or write data for any other tenant, location, or environment. Never embed an API key in a browser, mobile application, public repository, or client-side JavaScript bundle.