Authentication and permissions
Client credentials
kommuns is an OAuth 2 provider for the client credentials grant (RFC 6749 §4.4): your system authenticates as the integration, not as a person.
POST /oauth/token with grant_type=client_credentials and the client's id and secret, either as HTTP Basic
(Authorization: Basic base64(client_id:client_secret)) or as the form fields client_id / client_secret. Optional
scope: a space-separated subset of the integration's scopes (without it, the token gets them all).
| Answer | Meaning |
|---|---|
200 access_token, expires_in (3600), scope | Use the token for an hour. |
401 invalid_client | Unknown client id or wrong secret. |
400 unauthorized_client | The integration is turned off, disabled by kommuns, the plan doesn't include the API, or the organization is suspended. |
400 invalid_scope | A scope the integration doesn't have. |
400 unsupported_grant_type | Only client_credentials is supported. |
Send the token as Authorization: Bearer <token>. The organization comes from the token — never from a header you
send.
Tokens stop working at once when the integration's secret is renewed, it is turned off or deleted, its scopes are narrowed, kommuns disables it, or the plan no longer includes the API. Keep the secret in your system's secret store; if it leaks, renew it in Organization › Integrations.
Scopes
| Scope | Allows |
|---|---|
inventory:read | Locations, systems, equipment, sub-equipment. |
work_orders:read | Work orders, their status and assignees. |
work_orders:write | Create, change, assign, cancel, answer and complete work orders. |
issues:read | Feedback. |
issues:write | Create feedback (e.g. a sensor alarm). |
forms:read | The organization's forms and a work order's answers. |
files:read | Files (reserved for a later version). |
people:read | People and teams: names, e-mail, phone — personal data. Without it, assigned people appear only as ids. |
Permissions: scopes ∩ the integration's permissions
The integration is an identity of the organization. It is created with an organization permission definition and gets inventory permissions like a person, with Assign on a node (location, system, equipment); a permission there also applies below it as the definition says. For every record the API computes the integration's permission exactly as the app does for a person:
- Inventory: the nodes it has any permission on.
- Work orders: those whose node allows reading work orders, those assigned to the integration, those it created where it may create, and — for a service company — its customers' work orders assigned to the organization (with the organization's "incoming work orders" permission).
- Feedback: those whose node allows reading feedback.
- Writing follows the app's rules too, see Writing and completing work orders.
A record the integration may not read answers 404, as if it didn't exist.
Limits
The plan sets how many calls an integration may make per minute and how many integrations an organization may have.
Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds); over the limit the
API answers 429 rate_limited with Retry-After. Organization › Integrations shows each integration's calls today.