Quickstart

Get an access token and list the buildings your service can access. This takes about five minutes and confirms that your credentials and permissions work.

Before you begin

You need:

The client ID supplied with your KODE project delivery.
The private key registered for that client ID.
curl and jq, Node.js 18 or later, Python 3, or PowerShell 7.

Never commit a private key, client assertion, or access token to source control. Store secrets in an approved secrets manager.

Send your first request

Use the language menu on a sample to switch it. The other samples on this page follow that choice.

Create a client assertion

Sign a JWT client assertion with your private key, following RFC 7523. Then store it in an environment variable:

macOS and Linux

export KODE_CLIENT_ASSERTION="<signed-jwt>"

See Authentication for the full token flow.

Request an access token

Exchange the assertion for a short-lived access token:

cURL

export KODE_ACCESS_TOKEN=$(curl --fail-with-body --silent \
  --request POST "https://api.kodelabs.com/oauth2/v1/token" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=bms" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=${KODE_CLIENT_ASSERTION}" \
  | jq -r '.access_token')

$body = @{
  grant_type            = "client_credentials"
  scope                 = "bms"
  client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
  client_assertion      = $env:KODE_CLIENT_ASSERTION
}
$token = Invoke-RestMethod -Method Post -Uri "https://api.kodelabs.com/oauth2/v1/token" -Body $body
$env:KODE_ACCESS_TOKEN = $token.access_token

const body = new URLSearchParams({
  grant_type: "client_credentials",
  scope: "bms",
  client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  client_assertion: process.env.KODE_CLIENT_ASSERTION,
});
const response = await fetch("https://api.kodelabs.com/oauth2/v1/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body,
});
if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
const token = await response.json();
console.log(token.access_token);

import os
import requests

response = requests.post(
    "https://api.kodelabs.com/oauth2/v1/token",
    data={
        "grant_type": "client_credentials",
        "scope": "bms",
        "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
        "client_assertion": os.environ["KODE_CLIENT_ASSERTION"],
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["access_token"])

List your buildings

Send the token in the Authorization header:

cURL

curl --fail-with-body \
  "https://api.kodelabs.com/kodeos/api/v1/buildings?page=1&limit=50" \
  --header "Authorization: Bearer ${KODE_ACCESS_TOKEN}"

const response = await fetch(
  "https://api.kodelabs.com/kodeos/api/v1/buildings?page=1&limit=50",
  { headers: { Authorization: `Bearer ${process.env.KODE_ACCESS_TOKEN}` } },
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.json());

import os
import requests

response = requests.get(
    "https://api.kodelabs.com/kodeos/api/v1/buildings",
    params={"page": 1, "limit": 50},
    headers={"Authorization": f"Bearer {os.environ['KODE_ACCESS_TOKEN']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

A successful response returns 200 OK with a paginated data array:

{
  "data": [
    {
      "_id": "67c960faffaa42223163099e",
      "name": "KODE OS Office",
      "tz": "America/Detroit"
    }
  ],
  "itemCount": 1,
  "limit": 50,
  "page": 1,
  "pageCount": 1
}

If something goes wrong

Result	Likely cause	What to do
`401` from the token endpoint	Assertion is expired, unsigned, or uses the wrong key.	Create a new assertion with the registered private key.
`401` from the API	Access token is missing or expired.	Request a new access token.
Empty `data` array	Service account has no building assignments.	Ask your KODE project team to assign buildings.

Next steps

Try it in the playground

Paste your token and send the buildings request from the browser.

Ingest device data

Create devices and send point values from your system.

Fork in Postman

Copy the KODE API collection into your Postman workspace, then run the requests there.

Get started

Guides

API reference

Before you begin

Send your first request

If something goes wrong

Next steps

Try it in the playground

Ingest device data

Fork in Postman

​Before you begin

​Send your first request

​If something goes wrong

​Next steps

Try it in the playground

Ingest device data

Fork in Postman

Before you begin

Send your first request

If something goes wrong

Next steps