Introduction

Welcome to the Ochno Operated API Guide. This document will help you integrate your applications with the Ochno Operated platform, allowing you to securely access account, hub, and device data on behalf of your users or organisation.

If you’re new to APIs, think of them as a structured way for your system to talk to Ochno Operated programmatically—whether you want to read account details, update hub configurations, or build automations around the platform. This guide walks you through the full authentication flow and shows you how to retrieve the tokens required to make authorised API requests.

There are two ways to authenticate, depending on your use case:

Client Credentials Flow – ideal for server-to-server integrations that act on behalf of an organisation’s account.
→ See: “Retrieving Access (Client Credentials)”
Authorisation Code Flow – used when your integration needs to act on behalf of an authenticated end user.
→ See: “Code Exchange Authorisation”

Both sections explain the required setup in Ochno Operated → Account → Integrations, how to configure scopes, and how to exchange codes or credentials for access tokens.

Once authenticated, you can explore and interact with all available endpoints using our Swagger UI, where you can test requests, review parameters, and understand the full capabilities of the API.

Client Credentials Flow

Server2Server Integration guide (BETA)

Code Exchange Authorisation

Custom Ochno Operated OAuth2 integrations (beta)

Rest endpoints (swagger)

https://operated.ochno.com/doc/swagger/

Datatypes explanation:

States (simple)

{
  "state": {
    "connected": [0, 0, 0, 0],
    "active": 1,
    "mtrmode": true,
    "mtrport": 1,
    "mtrdisable": 0,
    "mtrextension": "disable",
    "mtrsync": true,
    "externalmtr": true,
    "adminmode": false,
    "otp": "normal"
  }
}

Internal system state. Only relevant values will be sent.

connected - The current connected "user" / upstream ports. 0 is disconnected, 1 is connected.
active - The current active port. Number is which port.
mtrmode - If UC mode is active. true if UC mode, false if BYOD mode. If missing UC mode is not configured.
mtrport - Which upstream port is used for UC system. Only available when configured to use it and mtrmode is true.
mtrdisable - Which downstream port is used for UC system . Only available when configured to use it and mtrmode is true.
mtrextension - If UC system is configured for Ochno Node. "port" | "disable", based on configuration.
mtrsync - When UC type is synced with a downstream OPC; true when UC mode, false when BYOD.
externalmtr - If UC mode is synced with the cloud. true = system is in meeting, false = system is idle.
adminmode - If the admin mode is enabled.
otp - Over Temperature Protection state. "normal" | "reduced" | "overheat"

OPC4 >= 1.0.x
(Not otp)

OPH4 >= 1.0.x
(supports connected, otp)

States (Connections / con)

Device path values may be any of the following: usb1, usb2, usb3, usb4

{
  "usb1": {
    "type": String,
    "connected": Boolean,
    "enabled": Boolean,
    "direction": String,
    "device": {
      "vid": Number,
      "pid": Number,
    },
    "charging": {
      "mode": String
      "requestedvoltage": Number, // Millivolt
      "requestedcurrent": Number // Milliampere
      "allocatedpower" : Number // Watt
    },
    "cable": {
      "vid": Number,
      "pid": Number
    },
    "displayport": {
      "multifunc": true,
      "enable": true,
      "dfpufp": Number
    },
    "altmode": {
      "role": String,
      "mode": String
    },
    "ochno": {
      "hwid": String,
      "port": Number
    }
  },
  ... same for all usb ports.
}

Information about usb ports. Data may vary a lot.

type - What type of usb port this is. "usb-c" | "usb-a" | "usb"
connected - If a device is connected.
enabled - If port is enabled or not. false means port does not even give power.
direction - What kind of data flow this port uses. "upstream" | "downstream" | "internal" (internal means directed internally, such as iot devices)
device - Values that are retrieved from the connected device.
  vid - Vendor id number. (Usually displayed as hex value to user.)
  pid - Product id number. (Usually displayed as hex value to user.)
charging - How the device has setup charging.
  mode - The current charging mode. "5V" | "SPR" | "PPS" | "EPR" | "LQC"
  requestedvoltage - Requested voltage by connected device.
  requestedcurrent - Requested max current by connected device.
  allocatedpower - How much power is allocated to this port.
cable - Information about the cable connected to the device.
  vid - Vendor id number of the cable. (Usually displayed as hex value to user.)
  pid - Product id number of the cablw. (Usually displayed as hex value to user.)
displayport - The connected device's displayport capabilities.
  multifunc - Multifunction mode preferred.
  enable - Functionality is enabled.
  dfpufp - If a DFP or UFP is connected.
altmode - The connected device's altmode capabilities.
  role - "UFP" or "DFP"
  mode - "DisplayPort" or "Thunderbolt"
ochno - If the connected device is from Ochno, more information can be made available.
  hwid - Hardware Id of connected ochno unit (example: O4E8EB1BEAAEA1)
  port - What port that it is connected to on the other unit.

OPC4 >= 1.0.x
(support type, connected, enabled, device, ochno)

OPC4 >= 1.1.x
(+ support cable, displayport, altmode)

OPH 1.0.x
(support type, connected, charging)

Configs

Name	Type	Range	Description	Support

Name	Type	Range	Description	Support
`adminalwaysoff`	`Boolean`		Set to disable admin mode from being activated. NOTE: This means the hub can no longer be accessed using OMC.	OPH4
`autoswitchconnect`	`String`	`‘off’ \| ‘on’ \| ‘always’`	Enables automatic video/USB switching when connecting device. `on` means the switching will happen only when nothing else is active. `always` means the switching will always happen on a new connect.	OPC3 OPC4
`autoswitchdisconnect`	`String`	`‘off’ \| ‘on’ \| ‘active’ \| 'both'`	Enables automatic video/USB switching when disconnecting device. `on` means the switching will happen only disconnecting the last device. `active` means the switching will always happen when disconnecting from active port.	OPC3 OPC4
`autoswitchports`	`Number`	`0-15` / `0b1111`	Controls which ports that trigger automatic switching. NOTE: This is a bit pattern where each bit control a port.	OPC3 OPC4
`buttondisabled`	`Number`	`0-15` / `0b1111`	Disable buttons from use.	OPC3 >= v1.4.3 OPC4
`buttonemptydisabled`	`Boolean`		Disables buttons from use when there is nothing connected to them.	OPC3 >= v1.6.8 OPC4
`buttonoffdefaultport`	`Boolean`		Enable to change to default port, instead of no port, when deactivating a port with a button.	OPC3 OPC4
`chargingprotocols`	`String[]`	`['SPR', ‘EPR’, ‘PPS’, ‘LQC’]`	Set what charging protocols that should be enabled.	OPH4
`defaultport`	`Number`	`0 = None` `1-4 = USB-C 1-4`	The initial port when booting system. This is also used by other settings: It is the port to change to when triggering auto switch disconnect, it may be the port a button moves to when deactivating a port. It is used in daisy-chain when a downstream hub tells the hub to activate a port.	OPC3 OPC4
`disabledfpusb3`	`Boolean`		Disable USB3 and video on ports that are not configured for Windows UC.	OPC4
`disableleds`	`Boolean`		Disable all LEDs on the hub hardware.	OPH4
`enabledports`	`Boolean[]`	`[true, true, true, true]`	Enable/disable specific upstream ports.	OPH4
`hdmiceccontrol`	`Boolean`		Enables HDMI CEC toggle.	OPC3 OPC4
`hdmipowerondelay`	`Number`	`0 = Always on` `1-126 = ms x 100` `127 = Always off`	Time to keep in reset for the HDMI 5V.	OPC3 >= v1.3.1 OPC4
`hpdondelay`	`Number`	`0 = Always on` `1-126 = ms x 100` `127 = Always off`	Time to keep in reset for the HPD.	OPC3 >= v1.3.1 OPC4
`inactivedisabled`	`Number`	`0-15` / `0b1111`	Disable the port when it is inactive.	OPC3 >= v1.3.1 OPC4
`lockactive`	`Number`	`0 = off` `1 = on`	Lock active port so it's not possible to switch away. This also works in daisy-chain, but all applicable hubs must be configured to use it.	OPC3 >= v1.6.8 OPC4
`mtrautoswitchreset`	`String`	`‘off’ \| ‘on’ \| ‘active’ \| 'both'`	Enables resetting UC mode memory when disconnecting devices. This is only relevant in combination with `mtrmodememory`.	OPC3 >= v1.4.3 OPC4
`mtrbuttoncycle`	`Boolean`		Enables device buttons to cycle between UC/BYOD mode on all buttons.	OPC3 OPC4
`mtrdefaultmodeports`	`Number`	`0-15` / `0b1111`	The default UC mode of individual ports, a set bit means UC mode	OPC3 OPC4
`mtrdisableusb`	`Number`	`0 = all USB-A` `1 = USB-A port 1` `2 = USB-A port 1`	Which USB to disable when in UC mode. `usemtr` must be set to `disable` to use this UC configuration.	OPC3 OPC4
`mtrkeepmodeinactive`	`Boolean`		If UC mode should be kept even during no active port.	OPC3 >= v1.4.3 OPC4
`mtrlongpressdelay`	`Number`	`0 = Off` `1-31 ms x 100`	Enables long press to switch UC modes. Value is duration for trigger.	OPC3 >= v1.4.3 OPC4
`mtrmanualinherit`	`Boolean`		Sets if a manual port change should inherit UC mode.	OPC3 OPC4
`mtrmodememory`	`Boolean`		If UC mode should be remembered after no active port. When set, this overwrites `mtrdefaultmodeports`. See setting `mtrautoswitchreset` for ways to reset memory.	OPC3 >= v1.4.3 OPC4
`mtronextension`	`Boolean`		Sets if the UC is placed on the extension USB-C port.	OPC4
`mtrport`	`Number`	`0 = Off` `1-6 = USB-C port 1-6`	The port that has an UC connected. `usemtr` must be set to `port` to use this UC configuration.	OPC3 OPC4
`noportperipheraloff`			Disable downstream ports with peripherals (not Ochno devices) when no port is active.	OPC4
`powerbalancingmode`	`String`	`‘static’ \| ‘firstprio’ \| ‘fairshare’`	Set the power distribution/balancing mode. Sibling setting: `usbpowerdistributionmode`	OPH4
`powerstatic`	`Number[]`	`[0-31, 0-31, 0-31, 0-31]` `Each value = W x 5` `Sum W < Unit max W`	Static power allocation per port. Sets the max allowed power per port.	OPC4 OPH4
`sharenetwork`	`Boolean`		Enables network sharing through the USB cable to the user laptop.	OPC4
`sharenetworkspeed`	`Boolean`		Protocol for network sharing (`false` = USB2, `true` = USB3). NOTE: Setting USB3 will force device on port 8 (USB-A 2) to only use USB2.	OPC4
`tysel7io`	`Boolean`		Enable to allow Ochno IO on port 7 (USB-A 1).	OPC4
`tysel8io`	`Boolean`		Enable to allow Ochno IO on port 8 (USB-A 2).	OPC4
`ufpdefaultrole`	`Number`	`0 = Sink` `1 = Source`	Default UFP port role for upstream ports. Only applicable if `ufprole` is set to DRP.	OPC4
`ufprole`	`Number`	`0 = Sink` `1 = Source` `2 = DRP`	UFP port role for upstream ports.	OPC4
`usbpowerdistributionmode`	`Number`	`0 = Disabled` `1 = First prio` `2 = Fair share`	Set the power distribution/balancing mode. Sibling setting: `powerbalancingmode`	OPC4
`usbpt2ondelay`	`Number`	`0 = Always on` `1-126 = ms x 100` `127 = Always off`	Time to keep in reset for USB passthrough USB 2 protocol.	OPC3 >= v1.3.1
`usbpt3ondelay`	`Number`	`0 = Always on` `1-126 = ms x 100` `127 = Always off`	Time to keep in reset for USB passthrough USB 3 protocol.	OPC3 >= v1.3.1
`usbptondelay`	`Number`	`0 = Always on` `1-126 = ms x 100` `127 = Always off`	Time to keep in reset for USB passthrough VBUS DET.	OPC3 >= v1.3.1 OPC4
`usbptusbcondelay`	`Number`	`0 = Always on` `1-126 = ms x 100` `127 = Always off`	Time to keep in reset for VBUS of the USB-C passthrough ports.	OPC4
`usbptvbusondelay`	`Number`	`0 = Always on` `1-126 = ms x 100` `127 = Always off`	Time to keep in reset for VBUS of the USB-A passthrough ports.	OPC3 >= v1.3.1 OPC4
`usemtr`	`String`	`'off' \| 'port' \| 'disable`	Enables UC configuration, see other UC settings ("`mtr...`").	OPC3 OPC4

Power

{
  "power": {
    "energy": Number, // Wh
    "duration": Number, // seconds    
    "voltage": Number, // Millivolt
    "current": Number // Milliampere
    "wattage" : Number // Watt
  }
}