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.

Sergio M avatar
Written by Sergio M
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

1. Context

Before starting, let's go over some context first. To keep Organizations and Devices separated 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 3 and 4 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 Organization TOKEN does not align with the intended Organization 4.

2. How to create an Organizational TOKEN

To create a TOKEN for an Organization, go to "Users" → "Organizations". Once there, follow these steps:

  1. Go into the organization you want to create the token for. To do this, just click on its name.

  2. Once on the view of that organization, go into the "tokens" section in the left panel.

  3. Click on the "+" button at the upper right corner of the screen.

  4. On the modal that opened up, define the following information:

    1. A name for the token.

    2. The API role for the token.

Once finished, click on the "save" button at the lower right corner of the modal.

3. 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_RETURNED.

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 see, the above request is rejected because the device ID has already been provisioned to another organization.

4. Managing Organizational Tokens

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

Other users also found useful...

Did this answer your question?