Skip to main content

Authentication and authorization

Authentication and authorization in a distributed system with many devices, deployments, user types, and users gets complicated quickly. At the same time it is critical to get this right, because mistakes can lead to leaks of sensitive customer data.

Transitive uses certificate-based authorization for all connected devices and clients, and exploits the namespace-structure of the shared data model for fine-grained authorization.


When a robot first registers with a Transitive deployment, whether it is or a self-hosted one, it receives a device-specific certificate from the portal. This certificate is used for authentication when connecting to the MQTT broker and it only gives access to the /org/device namespace. This means that even if one of your robots get highjacked and hacked, the attacker will only get access to this robot's own data, not the rest of the fleet.

Robot capabilities

Capabilities running on the robot are further restricted to only their own capability-specific namespace, i.e., /org/device/capScope/capName. This means that third-party capabilities cannot spy on other capabilities. This is similar to how iOS and Android protect against malware apps reading sensitive information used by other apps (e.g., banking apps).

Cloud capabilities

The cloud component of capabilities have access to their entire namespace across the entire fleet, i.e., /+/+/capScope/capName.

Web components

Web components are authenticated by provided JWT. This JWT encodes the permissions granted to the client (the user's browser session). The JWT is signed with the user's JWT secret. The JWT payload looks like:

"id": "USERID",
"device": "DEVICEID",
"capability": "@capScope/capName",
"userId": "user123", // a string that uniquely identifies a user in your context
"validity": 86400, // number of seconds this authentication should remain valid

This gives the JWT holder access to the named capability, but only for the named device and portal-user (org), and only for the specified number of seconds. It goes without saying that JWTs are only valid when signed with the JWT secret of the portal-user/org of the specified id. Note that userId (!= id) is for informational purposes only and allows giving a name to the front-end user who this JWT is being signed for (not signed by), e.g., a customer name.

In addition, all web components have read access to the /USERID/DEVICEID/@transitive-robotics/_robot-agent namespace, including when DEVICEID is _fleet, i.e., any JWT that gives access to the /USERID/_fleet/capScope/capName namespace also gets read access to the agent information of all devices in the users fleet, i.e., /USERID/_fleet/@transitive-robotics/_robot-agent.