Authentication
Every call carries one organization API token as a bearer token. The token decides which organization and which companies a request may reach, and whether it may read, write or both.
Organization API tokens
- Created by the organization’s administrator in the AI Zeny portal, under Organization → API tokens.
- Shown once when created; optionally limited to selected companies; optionally expiring.
- Given one permission when created — Read only, Write only, or Read and Write — that never changes; rotation keeps it. Tokens created before permissions existed are Read and Write.
- Sent as
Authorization: Bearer az_pat_…and nothing else: no Local API token, device token, session, PIN or password, and no token in a body or query string. - The token never reaches the PC.
Permissions
| Permission | What it may call |
|---|---|
| Read only | Every read: lists, reports, registers, saved queries and custom SQL, voucher and report PDFs, scripts and response transforms set up on the PC, and snapshots. Never a write or an integration run. |
| Write only | Every write and `/execute-integration`, plus two limited reads: `/companies` (codes, names and years in scope) and `/integration-run-status` (one run’s full record, including the data its writes returned and the script’s output). No other read. |
| Read and Write | Everything. |
The permission follows what an operation does, never its HTTP method: most reads are sent as POST. Printing a voucher to PDF is a read, although BUSY marks the voucher as printed. A script set up on the PC may call other systems when it runs; it still cannot change the books through a Read only token.
Refusals
| Refusal | Status and code |
|---|---|
| Missing, malformed, unknown or revoked token | 401 TOKEN_INVALID |
| Expired token | 401 TOKEN_EXPIRED |
| Organization suspended or closed | 403 ORGANIZATION_ACCESS_DISABLED |
| No active subscription with API access | 403 SUBSCRIPTION_REQUIRED, SUBSCRIPTION_INACTIVE, SUBSCRIPTION_EXPIRED, SUBSCRIPTION_SUSPENDED, SUBSCRIPTION_STATE_INVALID or FEATURE_NOT_ENTITLED |
| Company outside the token’s scope | 403 COMPANY_NOT_ALLOWED |
| Operation outside the token’s permission | 403 TOKEN_PERMISSION_DENIED |
| Permission could not be checked at that moment (retry) | 503 AUTHORIZATION_UNAVAILABLE |
| More financial years in one request than the plan covers | 403 FINANCIAL_YEAR_NOT_ALLOWED |
| More than 5 financial years in one request | 400 INVALID_PARAMETER |
The scope, permission and year refusals are decided in AI Zeny Cloud before anything is sent to the PC.
Rotation and revocation
Tokens can be rotated with an overlap window and revoked in the portal. The Knowledge Base describes each step.