Ubidots as a multi-device platform was designed intentionally to allow system integrators and OEMs to create devices in tandem with the first data point received to Ubidots platform.

With Ubidots Organizational tokens, Ubidots Administrator accounts can now create TOKENS and provision devices specifically to a predetermined organization; now bypassing having to assign each device to an Organization within your application's architecture. 

Step 1: How to create an Organizational TOKEN
Step 2: Using the Org TOKEN to create a device
Step 3: Set permissions to the Organizational TOKEN
Step 4: GET all the TOKENS of an Organization 


Bit of background, to keep Organizations and Devices separate and organized correctly, Ubidots uses a two-tier device identifier model – TOKENS and Device Labels. First, the Ubidots TOKEN is the key for each piece of hardware to send data to Ubidots; every Ubidots account has a parent TOKEN, or using this tutorial below you can create a subtoken called an Organization TOKEN, the key for each Organization's data within your application's architecture. The second tier for Ubidots device identification is Device Labels, which are unique identifiers per device, across a single Ubidots Administrator's account. Using both the TOKEN and Device Label, Ubidots users keep their data associated with the right hardware data in the right places. 

In the below diagram we can see the quadrants II and IV are incorrect logic and any attempt to send data through these structures will be rejected. In quadrant 3 we see a repeated Device ID, which will be rejected as it has been claimed already. In quadrant 4 we see a rejection because the Org TOKEN does not align with the intended Org 4.

Step 1: How to create an Organizational TOKEN

To create a TOKEN for an Organization or a subtoken to your parent TOKEN, we must first have an Organization created and know its Organization ID. 

For this tutorial's understanding, we have already created an Organization titled "Lola's Machines." And, this Org has automatically been assigned the ID=1767.  To find your Organization's ID, enter to the Organization section of your Ubidots account and select the single Organization you wish to create a TOKEN for. Located at the end of the URL in your browser of the Organization's Overview you will find the ID assigned to each organization. Please, reference the image below for a better idea to locating the organization's ID:

Now that you know your Organization ID, you will need the Ubidots API Key to create the Organization's TOKEN. 

To create an Organization TOKEN through the API, make a POST request from your computer's terminal with the structure below assigning credentials along the way, where indicated.

Structure of the POST Request:

curl -XPOST -H "x-ubidots-apikey: <APIKEY>" -H "content-type: application/json" -d '{"name": "<TOKEN_NAME>"}' http://industrial.api.ubidots.com/api/v1.6/auth/tokens/organizations/<ORG_ID>/

APIKEY  == Administrator Account's API KEY
TOKEN_NAME == Custom assign a new TOKEN name as you see fit.
ORG_ID == see above to find Org ID

Example POST Request:

curl -XPOST -H "x-ubidots-apikey: BBFF-abcde5bd9abcdfd723b1a9avbfc4cdeb55cd" -H "content-type: application/json" -d '{"name": "Token1"}' http://industrial.api.ubidots.com/api/v1.6/auth/tokens/organizations/1767/

Resulting Command Response with New TOKEN:

{"name": "Token1", "token": "BBFF-kSTyqOiOuMda6oIKIkj5YErielN8C9", "id": 2674}

Step 2: Using the Org TOKEN to create a device

Now that you have the organization TOKEN created, you are now able to manage your devices and variables using Ubidots API. 

1. The POST request below automatically creates a new device with a variable assigned to the organization of the new TOKEN returned.

Structure of the POST Request:

curl -XPOST -H "x-auth-token: <TOKEN_RETURNED>" -H "content-type: application/json" -d '{"VARIABLE_LABEL": VALUE}' http://industrial.api.ubidots.com/api/v1.6/devices/<DEVICE_LABEL>

Example of POST Request: 

curl -XPOST -H "x-auth-token: BBFF-kSTyqOiOuMda6oIKIkj5YErielN8C9" -H "content-type: application/json" -d '{"humidity": 22}' http://industrial.api.ubidots.com/api/v1.6/devices/new-device

As you can see in the example request above, we are assigning the device label "new-device" with a variable "humidity" to the organization of the TOKEN returned.

Resulting Command Response:

{"humidity": [{"status_code": 201}]}

 Now that we have a successful response from the server. Go to your Device section of your Ubidots application and visualize the device created for the Organization.

As you can see above, the device is automatically assigned to the organization of the TOKEN_RETURN. 

NOTE: If the device label assigned in the request is already created in the Organization, the variable set will update anytime data is sent from that device.  

2. As described previously, if both the TOKEN and Device ID are not properly ordered, your first attempt to send data to Ubidots will be rejected.

Using the TOKEN_RETURN we try to update a device that has already been assigned to another Organization by the device ID (Quadrant 3 in the illustration above).

curl -XPOST -H "x-auth-token: BBFF-kSTyqOiOuMda6oIKIkj5YErielN8C9" -H "content-type: application/json" -d '{"humidity": 22}' http://industrial.api.ubidots.com/api/v1.6/devices/500027000d51353432383931

Resulting Response:

{"detail": "You do not have permission to perform this action."}

As you could conclude, the above the request is rejected because the device ID has already been provisioned to another organization.

Step 3: Set permissions to the Organizational Token 

To customize permissions of your users and organizations, go to the Groups tab within the Organizations dropdown. Just below Users in the Organization's left pane menu, select Groups to assigned user capabilities and permissions within your organization:

Step 4: GET all the TOKENS of an Organization 

The Ubidots API also lets you receive all TOKENS associated to an Organization, simply make the following GET requests, adding your accounts credentials where indicated:

Structure for GET Request: 

curl -X GET -H "x-ubidots-apikey: <APIKEY>" -H "content-type: application/json" http://industrial.api.ubidots.com/api/v1.6/auth/tokens/organizations/<ORG_ID>/

Example GET Request: 

curl -X GET -H "x-ubidots-apikey: BBFF-abcde5bd9abcdfd723b1a9avbfc4cdeb55cd" -H "content-type: application/json" http://industrial.api.ubidots.com/api/v1.6/auth/tokens/organizations/1767/

Resulting Response:

{"count": 4, "next": null, "previous": null, "results": [{"name": "Token1", "token": "BBFF-kSTyqOiOuMda6oIKIkj5YErielN8C9", "id": 2674}]}

Now it is your turn to create multi device applications effortlessly and affordably. For more application ideas, check our Ubidots Help Center or always feel free to reach out to Ubidots Support team with any additional questions or thoughts. 

Happy Hacking :) 

Did this answer your question?