Public API Authentication Upgrade - Introducing OAuth 2.0 for KODE OS

Public API Authentication Upgrade - Introducing OAuth 2.0 for KODE OS

Overview

We are enhancing the authentication mechanism for the KODE OS Public API by introducing OAuth 2.0. This update brings stronger security, flexible access controls, and greater visibility for integrations built on our API platform.

Overview & Objective

The new OAuth 2.0 authentication framework enables developers to authenticate securely using service accounts and control access with fine-grained permissions. This upgrade offers a scalable, secure, and enterprise-ready API platform that adheres to industry-leading standards.

What’s New

  • OAuth 2.0 Authentication: Token-based access via industry-standard authorization protocol

  • Service Accounts: Create dedicated credentials for each integration or service

  • Granular Permission Control: Define exact access scopes for services and data types

  • Scoped Access by Building: Restrict or enable access per building, offering precise control over environments

  • Centralized Account Management: All service accounts can be managed through Launchpad

  • Versioned API Structure: Updated all endpoints to follow a standardized /api/v1/ path format for clarity and long-term maintainability.

Available Scopes

  • Read Buildings (required for all other scopes)

  • Read/Add Devices

  • Read Building Areas

  • Read/Add/Write Point Metadata

  • Read/Create Timeseries

Key Benefits

  • Improved Security - OAuth 2.0 enables token-based authentication that limits exposure and increases control

  • Controlled Access - Define exactly what data and features a service account can access using scopes

  • Scalable Integration - Assign service accounts per project or team, making it easier to manage large deployments

  • Visibility & Auditing - Know which account has access on what, across different buildings and services

  • Simplified Management - Easily create, modify, and revoke service accounts using Launchpad’s user interface

Target Audience

External developers building or maintaining integrations with the KODE OS Public API.

Documentation & Setup Guide

The updated API documentation, including OAuth 2.0 setup instructions, is now available here:  https://documenter.getpostman.com/view/37847641/2sAYkEqfGB

Service Account Management

Learn more about creating and managing Service Account by visiting the following article: Service Account Setup

API Endpoint Changes Summary

Effective Path Structure Update – `/api/v1/` Standardization

To improve consistency, versioning, and maintainability, we’ve updated the structure of several API endpoints under the `/kodeos` path. This document outlines the changes from the previous (legacy) paths to the new versioned structure.

Summary of Endpoint Changes


Functionality

Old Endpoint

New Endpoint

List Buildings

/kodeos/api/buildings

/kodeos/api/v1/buildings

Get Areas of a Building

/kodeos/api/buildings/{buildingId}/areas

/kodeos/api/v1/buildings/:buildingId/areas

List Datasources

/kodeos/api/buildings/{buildingId}/datasources

/kodeos/api/v1/buildings/:buildingId/integrations/datasources

Datasource Actions

/kodeos/api/buildings/{buildingId}/datasources/{datasourceId}/actions

/kodeos/api/v1/buildings/:buildingId/integrations/datasources/:datasourceId/actions

Action Fields

/kodeos/api/buildings/{buildingId}/datasources/{datasourceId}/actions/{action}/fields

/kodeos/api/v1/buildings/:buildingId/integrations/datasources/:datasourceId/actions/:action/fields

Invoke Action

/kodeos/api/buildings/{buildingId}/datasources/{datasourceId}/actions/{action}/invoke

/kodeos/api/v1/buildings/:buildingId/integrations/datasources/:datasourceId/actions/:action/invoke

List Devices

/kodeos/api/buildings/{buildingId}/devices

/kodeos/api/v1/buildings/:buildingId/devices

Create Device

/kodeos/api/buildings/{buildingId}/datasources/{datasourceId}/device/create

/kodeos/api/v1/buildings/:buildingId/integrations/datasources/:datasourceId/devices

Create Devices (Batch)

/kodeos/api/buildings/{buildingId}/datasources/{datasourceId}/device/create-batch

/kodeos/api/v1/buildings/:buildingId/integrations/datasources/:datasourceId/devices/batch

List Points

/kodeos/api/buildings/{buildingId}/points

/kodeos/api/v1/buildings/:buildingId/points

Timeseries (all & by point)

/kodeos/api/buildings/{buildingId}/points/timeseries
/kodeos/api/buildings/{buildingId}/points/timeseries/{pointId}

/kodeos/api/v1/buildings/:buildingId/timeseries

Write to Point

/kodeos/api/buildings/{buildingId}/points/write-action/{pointId}

/kodeos/api/v1/buildings/:buildingId/integrations/datasources/:datasourceId/devices/:deviceId/points/:pointId/fields

Invoke Point Action

/kodeos/api/buildings/{buildingId}/points/invoke-action/{pointId}

/kodeos/api/v1/buildings/:buildingId/integrations/datasources/:datasourceId/devices/:deviceId/points/:pointId/write

Datasource Timeseries (all)

/kodeos/api/buildings/{buildingId}/datasources/{datasourceId}/timeseries

/kodeos/api/v1/buildings/:buildingId/integrations/datasources/:datasourceId/timeseries

Datasource Timeseries (by device)

/kodeos/api/buildings/{buildingId}/datasources/{datasourceId}/timeseries/{deviceId}

/kodeos/api/v1/buildings/:buildingId/integrations/datasources/:datasourceId/devices/:deviceId/timeseries

Datasource Timeseries (by device & point)

/kodeos/api/buildings/{buildingId}/datasources/{datasourceId}/timeseries/{deviceId}/point/{pointId}

/kodeos/api/v1/buildings/:buildingId/integrations/datasources/:datasourceId/devices/:deviceId/points/:pointId/timeseries

Frequently Asked Questions

  1. What is changing with the KODE OS Public API authentication?

    1. The authentication method is being upgraded from API key-based access to OAuth 2.0 with service accounts and granular permission control.

  2. What is OAuth 2.0?

    1. OAuth 2.0 is a secure token-based access authentication method.

  3. Why is this change happening?

    1. To improve security, allow developers to manage specific permissions per integration, and provide better visibility into API usage.

  4. What are granular permissions?

    1. Granular permissions allow precise control over what data and actions a service account can access or perform, using scopes, like "Read Buildings," "Read Devices and Add Devices," "Write Points," and "Read Timeseries."

  5. How do I manage service accounts?

    1. Service accounts are managed via the Launchpad platform.

  6. Will the Public API endpoints or data structures change?

    1. No, only the authentication method is changing.

  7. Can permissions be configured per building?

    1. Yes, permissions can be scoped to access a single building or multiple buildings.

  8. Where can I find the updated KODE OS Public API documentation?

    1. The updated documentation is available at https://documenter.getpostman.com/view/37847641/2sAYkEqfGB

  9. How do I create a new service account?

    1. Log in to Launchpad, navigate to the Company section, click on Service Account, and then click Add New Service.

  10. Can keys have expiration dates?

    1. Yes, each key can have its own expiration date and notification settings.

    • Related Articles

    • KODE OS 2.0 - A redesigned KODE OS, built for amazing experiences

      Dec 5, 2023 Today we’re introducing a major design update to KODE OS - going live today for your organization as a KODE Labs early adopter, and rolling out to our global installed base in general release over the coming months. With its better ...

    • KODE OS Release - Work Order integration!

      KODE OS is constantly shipping new features and updates to improve the overall user experience. We have put together this round-up of some notable enhancements to walk you through the new Work Order feature release, which will take place on ...

    • KODE OS Product Release - Sep 30, 2021

      KODE Labs is releasing 3 big features that will enhance and personalize the user experience. Insights on Site Details Current Insights capabilities will be available on Site Details (Building Dashboard).  You will be able to add widgets, charts, ...

    • KODE OS Enhanced Notification System: Connectivity Notifications & Custom Email Templates

      Get ready for an exciting upgrade to the KODE OS experience! With our latest release, we are improving how you receive and customize your notifications. Let's dive right into it. Enhanced Customization and Connectivity The KODE OS notification engine ...

    • KODE OS Mobile Restructure

      KODE 2.0 is LIVE! We're thrilled to introduce a complete rebuild of our mobile platform, transforming building management into an effortlessly intuitive experience. Our focus? Clarity, ease, and power-packed features. Before All modules were bundled ...