Getting started

1. Create an integration

Someone with the Integrations permission in the organization (organization administrators have it):

1. Opens Organization › Integrations and clicks New integration.
2. Gives it a name (shown in the activity log and the Assignees lists), chooses its scopes and an organization permission definition.
3. Copies the client id and client secret from the window that opens — the secret is shown only now.

Then gives the integration permissions on the inventory it should see, the same way as for a person: on a location (or system, equipment) Assignees › Assign, choose the integration and a permission definition.

If Organization › Integrations says the plan doesn't include the API, the organization needs a plan with the API.

2. Get an access token

The examples use the API base https://app.kommuns.com/api/public/v1 as $KOMMUNS_API.

curl

export KOMMUNS_API="https://app.kommuns.com/api/public/v1"
curl -s -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials "$KOMMUNS_API/oauth/token"

Python

import os
import requests

API = os.environ["KOMMUNS_API"]
response = requests.post(f"{API}/oauth/token", data={"grant_type": "client_credentials"},
                         auth=(os.environ["CLIENT_ID"], os.environ["CLIENT_SECRET"]), timeout=10)
response.raise_for_status()
token = response.json()["access_token"]

Node.js

const API = process.env.KOMMUNS_API;
const basic = Buffer.from(`${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`).toString('base64');
const res = await fetch(`${API}/oauth/token`, {
  method: 'POST',
  headers: {authorization: `Basic ${basic}`, 'content-type': 'application/x-www-form-urlencoded'},
  body: 'grant_type=client_credentials',
});
const {access_token: token} = await res.json();

The answer:

{"access_token": "kmns_at_…", "token_type": "Bearer", "expires_in": 3600, "scope": "inventory:read work_orders:read"}

A token lasts an hour; get a new one when it expires (or when a call answers 401).

3. Call the API

curl -s -H "Authorization: Bearer $TOKEN" "$KOMMUNS_API/me"
curl -s -H "Authorization: Bearer $TOKEN" "$KOMMUNS_API/work-orders?status=open,in_progress&limit=20"

/me tells which integration and organization the token belongs to, its scopes and the per-minute limit. Next read Authentication and permissions and the conventions every endpoint follows.