Más a menudo de lo que se podría pensar, se vuelve necesario no solo tener usuarios accediendo a tu aplicación impulsada por Ubidots bajo un conjunto dado de permisos, conocidos como Roles de Usuario, sino también la capacidad de tener Tokens consumiendo la API de Ubidots bajo roles similares. Eso es exactamente lo que son los Roles Organizacionales, un conjunto de permisos que restringen el acceso que un Token puede tener a los recursos de una organización.

Los Roles Organizacionales se pueden encontrar en la sección de Credenciales API de tu cuenta, justo debajo de los Tokens. En términos simples, así como existen Roles de Usuario para restringir el acceso y las operaciones de cualquier usuario dado sobre secciones de la aplicación –Dispositivos, Datos, Usuarios–, los Roles Organizacionales hacen lo mismo para Tokens Organizacionales, dotando a los Tokens de permisos sobre ciertas entidades, por ejemplo, Dispositivos, y las operaciones CRUD que esos Tokens pueden realizar. Debido a esto, los Roles Organizacionales son importantes como una herramienta para proteger tu aplicación y aumentar su seguridad contra un uso inapropiado, en caso de que un token organizacional sea comprometido.
​
​NOTA: En el momento de escribir este artículo, los Roles Organizacionales solo abarcan acciones CRUD sobre Dispositivos y sus sub-entidades, es decir, variables y valores, Grupos de Dispositivos y Eventos.

Desde la sección de Credenciales API, sigue los siguientes pasos para crear un Rol Organizacional para tus Tokens Organizacionales:
​
​Paso 1: Haz clic en el botón “+” justo debajo del título Roles Organizacionales
​Paso 2: Nombra e ingresa una Descripción (Opcional) para tu Rol
​Paso 3: Selecciona los Permisos que los tokens organizacionales tendrán sobre Dispositivos y sus sub-entidades, Grupos de Dispositivos o Eventos
​Paso 4: Haz clic en la marca de verificación verde
​

Con un Rol Organizacional ya creado, ahora es momento de usarlo. Para ello, ve a una Organización, selecciona la sub-sección Tokens en el panel izquierdo, y sigue los siguientes pasos:
​
​Paso 1: Haz clic en el botón “+” en la esquina superior derecha
​Paso 2: Ingresa un nombre para tu Token Organizacional y haz clic en la flecha en la esquina inferior izquierda
​Paso 3: Selecciona el Rol Organizacional para el Token
​Paso 4: Haz clic en la marca de verificación verde

Con fines de prueba, creamos un Rol Organizacional con permisos de solo lectura sobre Dispositivos, Variables y Valores, es decir, todos los Tokens Organizacionales bajo dicho Rol solo podrán Leer datos de los Dispositivos asignados a la respectiva organización:

Con ese fin, aquí hay 2 ejemplos usando un Token bajo este Rol Organizacional de solo lectura haciendo las solicitudes con comandos cURL:
​
​Ejemplo 1: Solicitud GET para recuperar el último valor de una variable

Ejemplo 2: Solicitud POST para enviar un valor al mismo dispositivo en la Organización

Dada la naturaleza de solo lectura de este Token, no es posible enviar datos a Ubidots, de ahí la respuesta de la API que indica “No tienes permiso para realizar esta acción.”