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.


  • CRUD: Create, Read/View, Update, Delete


  1. Active Ubidots account (Not STEM)

  2. Active organization

Table of Content

  1. Explaining Organizational Roles

  2. Create an Organizational API Role

  3. Organizational Tokens under an Organizational API Role

  4. 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. Create 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 \

Example 2: POST request to send a value to the same device in the Organization

curl -X POST \
-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.”

Other users also found useful...

Did this answer your question?