> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Authenticate with the KODE API and list the buildings your service can access.

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.

> [!WARNING]
>
> 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.

**1. Create a client assertion**

Sign a JWT client assertion with your private key, following [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523). Then store it in an environment variable:

```bash macOS and Linux theme={"theme":{"light":"github-light","dark":"github-dark"}}
export KODE_CLIENT_ASSERTION="<signed-jwt>"
```

```powershell PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:KODE_CLIENT_ASSERTION = "<signed-jwt>"
```

See [Authentication](https://docs.kodelabs.com/products/kode-api/authentication.md) for the full token flow.

**2. Request an access token**

Exchange the assertion for a short-lived access token:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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')
```

```powershell PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
$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
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"])
```

**3. List your buildings**

Send the token in the `Authorization` header:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --fail-with-body \
  "https://api.kodelabs.com/kodeos/api/v1/buildings?page=1&limit=50" \
  --header "Authorization: Bearer ${KODE_ACCESS_TOKEN}"
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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());
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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())
```

```powershell PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
$headers = @{ Authorization = "Bearer $env:KODE_ACCESS_TOKEN" }
Invoke-RestMethod -Uri "https://api.kodelabs.com/kodeos/api/v1/buildings?page=1&limit=50" -Headers $headers
```

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

> [card] [Try it in the playground](https://docs.kodelabs.com/products/kode-api/api-reference/buildings/list-buildings.md?playground=open)
>
> Paste your token and send the buildings request from the browser.

> [card] [Ingest device data](https://docs.kodelabs.com/products/kode-api/guides/ingest-device-data.md)
>
> Create devices and send point values from your system.

> [card] [Fork in Postman](https://elements.getpostman.com/view/fork?collection=37847641-0db06e08-772a-492b-9a93-f5d18c67b15c\&documenterCollectionId=37847641-0db06e08-772a-492b-9a93-f5d18c67b15c-2sAYkEqfGB\&referrer=https%3A%2F%2Fdocumenter.getpostman.com%2Fview%2F37847641%2F2sAYkEqfGB\&versionTag=latest\&source=documenter)
>
> Copy the KODE API collection into your Postman workspace, then run the requests there.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.