Authentication and tenant boundaries
Use Authorization: Bearer <key> from your application backend. Tenant IDs are
identifiers, not secrets or permission grants. Each request rechecks the key,
its current issuer permissions and its allowed tenant.
In production, tenant access comes only from an explicit grant that Ivora assigns to your account. Signing in or owning a Host account grants no tenant access by itself. Only users with a grant, Ivora staff included, can create workspaces and API keys, and a tenant API key keeps working only while its issuer's grant does.
| Credential | Intended use |
|---|---|
| Signed-in user token | Developer onboarding and key management |
| Scoped tenant API key | Backend inventory, commands, billing and managed payments |
| Workspace key/scopes | Isolated simulation; no automatic access to physical chargers |
Diagram source
flowchart LR
Request[Backend request] --> Key[Valid active key]
Key --> Issuer[Current grant]
Issuer --> Tenant[Allowed tenant]
Tenant --> Scope[Required scope]
Scope --> Resource[Tenant-owned resource]
Resource --> Result[Operation permitted]| Scope | Capability |
|---|---|
stations:read | Read locations, stations, connector state and charger displays |
stations:write | Provision inventory, connection credentials and charger displays |
stations:control | Start, stop, reset, unlock and change availability |
billing:read | Read transactions, tariffs, bills and payment status |
billing:write | Create/finalize bills, record billing alerts and authorize, capture or release payments |
billing:refund | Refund a captured payment |
settlement:write | Opt into external sessions and report processor outcomes |
Managed bill start requires both billing:write and stations:control.
External start additionally requires settlement:write; existing keys do not
automatically gain the new scope. Refunds require billing:refund: keys that
held billing:write before September 29 received it once, and new keys must
request it. Display adapters are administered by Ivora
staff; tenant applications never need those routes. Store credentials
server-side, redact them from logs and revoke unused keys. Use a separate
read-only key for investigation.
Do not expose a broad credential to an end-user chatbot. Put the assistant behind your application's host/guest permission checks. See AI integration.
Signed-in users only
Some actions accept only a signed-in user's token and refuse every API key:
creating keys and workspaces, and changing a tenant's
payment account (onboarding and
disconnect need the tenant's tenant-admin role). Reading the payment account
needs only billing:read. Pinning or approving a payment account and setting an
API key's rate limit are Ivora staff actions.
Rate limits
Each API key may make 180 requests a minute by default. Further requests return
429 rate_limited; wait and retry with the same idempotency key. Ivora can set a
key's own limit between 1 and 1,200 requests a minute on request; a change takes
effect within a minute.