More often than not, it becomes necessary to not only have users accessing your Ubidots powered App under a given set of permissions, known as Users Roles, but also the ability of having Tokens consuming Ubidots’ API under similar roles. That’s exactly what Organizational Roles are, a set of permissions that restrict the access a Token can have to an organization resources.
Abbreviations
CRUD: Create, Read/View, Update, Delete
Requirements
Active Ubidots account (Not STEM)
Table of Content
Explaining Organizational Roles
Creating an Organizational API Role
Organizational Tokens under an Organizational API Role
Using Organizational Tokens under an Organizational API Role.
1. Explaining Organizational Roles
Organizational Roles can be found in your account’s API Credentials section, just below the Tokens. Simply put, just as there are User Roles to restrict access and operations of any given user over app sections –Devices, Data, Users–, Organizational Roles do the same to Organizational Tokens, they endow Tokens with permissions over certain entities, for example, Devices, and the CRUD operations those Tokens can perform. Because of this, Organizational Roles are important as a tool to shield your application and level up its security against inappropriate usage, should an Organizational token be compromised.
NOTE: At the moment of writing this article, Organizational Roles only scope CRUD actions over Devices and its sub-entities, that is, variables and values, Device Groups and Events.
2. Creating an Organizational API Role
From the API Credentials section, follow the below steps to create an Organizational Role for your Organizational Tokens:
Step 1: Click the “+” button just below the Organizational Roles title
Step 2: Name and input a Description (Optional) for your Role
Step 3: Select the Permissions the Organizational tokens will have over Device and its sub-entities, Device Groups or Events
Step 4: Click the green check-mark
3. Organizational Tokens under an Organizational API Role
With an Organizational Role already created, now it is time to use it. To this, go to an Organization, select the Tokens sub-section in the left panel, and follow the below steps:
Step 1: Click the “+” button on the top-right corner
Step 2: Enter a name for your Organizational Token and click the arrow in the bottom-left corner
Step 3: Select the Organizational Role for the Token
Step 4: Click the green check-mark
4. Using Organizational Tokens under an Organizational API Role
For testing purposes, we created an Organizational Role with View-only permissions over Devices, Variable and Values, that is, all Organizational Tokens under such Role will only be able to Read data from Devices assigned to the respective organization:
To that end, here are 2 examples using a Token under this Read-only Organizational Role making the requests with cURL commands:
Example 1: GET request to retrieve a variable last value
curl -G https://industrial.api.ubidots.com/api/v1.6/devices/DEV_LABEL/VAR_LABEL/lv \
-d 'token=ORGANIZATIONAL_TOKEN'
Example 2: POST request to send a value to the same device in the Organization
curl -X POST https://industrial.api.ubidots.com/api/v1.6/devices/DEV_LABEL \
-H 'X-Auth-Token:ORGANIZATIONAL_TOKEN' \
-H 'Content-Type:application/json' \
-d '{"VAR_LABEL": 10}'
Given the Read-only nature of this Token, sending data to Ubidots is not possible, hence the API response stating “You do not have permission to perform this action.”