All Collections
Developer Guides
Organizational Tokens: Creating Tokens for a specific Organization
Organizational Tokens: Creating Tokens for a specific Organization
Learn how to create Organizational Tokens with Ubidots API
Isabel Lopez avatar
Written by Isabel Lopez
Updated over a week ago

With organizational tokens, Ubidots admin accounts can create TOKENS and provision devices specifically to a predetermined organization. With them, you'll avoid having to assign each device to an Organization within your App's architecture. 

Table of Contents

Before starting, let's go over some context first. 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. With this guide you'll learn how to create a subtoken called "Organization token", the key for each Organization's data within your application's architecture. The second tier for Ubidots device identification are 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 have an 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 by Organization 1 already. In quadrant 4 we see a rejection because the Org. TOKEN does not align with the intended Organization 4.

1. How to create an Organizational TOKEN

To create a TOKEN for an Organization, we must first have an Organization created and know its ID

For this tutorial, we have already created an Organization called "Organization 1", which has automatically been assigned the ID 42573. To find your Organization's ID, go to the Organization section of your Ubidots account and select the Organization you wish to create a TOKEN for. Located at the end of the URL in your browser (after getting into the Organization's overview) you will find the ID assigned to each organization. The image below illustrates this:

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 following structure, 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>"}'<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

POST request example:

curl -XPOST -H "x-ubidots-apikey: BBFF-abcde5bd9abcdfd723b1a9avbfc4cdeb55cd" -H "content-type: application/json" -d '{"name": "Token1"}'

Resulting command response with new TOKEN:

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

2. Using the Org TOKEN to create a device

Now that you have the organization TOKEN created, you can manage 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 a POST request:

curl -XPOST -H "x-auth-token: <TOKEN_RETURNED>" -H "content-type: application/json" -d '{"VARIABLE_LABEL": VALUE}'<DEVICE_LABEL>

Example of a POST request: 

curl -XPOST -H "x-auth-token: BBFF-kSTyqOiOuMda6oIKIkj5YErielN8C9" -H "content-type: application/json" -d '{"humidity": 22}'

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 the Device section of your Ubidots application where you'll see 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, the POST 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}'

Resulting response:

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

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

3. Managing Organizational Token 

To access and manage an Organization's Tokens, simply go to the "Tokens" section of the Organization's settings. 

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"<ORG_ID>/

Example GET request: 

curl -X GET -H "x-ubidots-apikey: BBFF-abcde5bd9abcdfd723b1a9avbfc4cdeb55cd" -H "content-type: application/json"

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?