Permissions (scopes)
When creating a token you choose what it may do. You can only grant permissions that you have yourself in the management app.
| Scope | Allows | The creator needs |
|---|---|---|
locations:read | Read garage parks | Locations (view) |
occupancy:read | Read occupancy rates (current, history, per garage type) | Occupancy plan (view) |
tenants:read | Read tenants (without bank details) | Tenants (view), Leasing process (view) |
tenants:import | Submit existing tenants to the import | Data import (edit), Leasing process (view) |
tenants:import_commit | Take over imported existing tenants (creates tenants and leases) | Data import (edit), Leasing process (edit) |
bookings:read | Read booking journal and revenue | Accounting overview (view) |
open_items:read | Read open items | Receivables (view) |
dunning:read | Read dunning status and issued dunning notices | Receivables (view) |
invoices:read | Read invoices | Invoices (view) |
payments:read | Read incoming payments (without bank details) | Payments (view), Accounting overview (view) |
payments:read_counterparty | Add-on to payments:read: bank details and payment reference of payers | Payments (view), Accounting overview (view) |
emails:read | Read sent emails (subject, status, preview) | Email log (view), Tenants (view) |
emails:read_body | Add-on to emails:read: full text of emails | Email log (view), Tenants (view) |
usage:read | Read the access log of your own API calls | API access (view) |
documents:read | Read documents (tenant and location documents, file details only) | Tenants (view), Locations (view) |
documents:download | Add-on to documents:read: short-lived download links for documents | Tenants (view), Locations (view) |
contractors:read | Read contractors and orders | Articles and contractors (view), Garages/units (view), Leasing process (view) |
units:read | Read units and garages | Garages/units (view), Locations (view) |
contracts:read | Read contracts, amendments and terminations | Leasing process (view), Tenants (view) |
datev:export | Retrieve and start DATEV exports | Financial accounting (view) |
prospects:read | Read prospects and the waiting list | Leasing process (view) |
prospects:write | Add-on to prospects:read: submit prospect enquiries | Leasing process (edit) |
appointments:read | Read appointments | Calendar (view) |
appointments:write | Add-on to appointments:read: create appointments | Calendar (edit) |
damages:read | Read damage reports | Garages/units (view), Leasing process (view) |
damages:write | Add-on to damages:read: create damage reports and set status | Garages/units (edit), Leasing process (edit) |
utility:read | Read utility statements, meters and meter readings | Meter readings (view), Electricity (view), Water (view) |
utility:write | Add-on to utility:read: enter meter readings | Meter readings (edit), Electricity (edit), Water (edit) |
webhooks:manage | Set up and manage webhooks | API access (full access) |
timeline:read | Read a tenant timeline (only events the token may also read) | Tenants (view) |
Add-on scopes: some scopes extend another one and allow nothing on their own: payments:read_counterparty (bank details of payers), documents:download (download links), emails:read_body (full text of emails) and the write scopes utility:write (meter readings), damages:write (damage reports), appointments:write (appointments) and prospects:write (prospects). The token also needs the base scope (…:read). A token may carry up to 40 scopes. It always sees the whole organization — there is no restriction to individual locations on the token.
If a token lacks the required scope, the API responds with 403 insufficient_scope and names the required scope in the field error.required_scope.
The creator's permissions are checked again on every request. If the person who created the token loses a required permission — including the API access permission itself — the API immediately responds with 403 insufficient_permissions. Once the permission is restored, the token works again.