Qué puede hacer cada usuario

Cada sección lista los comandos para ejecutar esa capacidad y un ✓ que indica que ya está implementado y verificado en el código.

Tabla de permisos — Distribuidores (Dealer)

Estos roles aplican dentro de la organización de un distribuidor (dealer) y de sus sub-organizaciones. Por seguridad, si un usuario no tiene ningún rol asignado en esa organización, no podrá ver ni hacer nada ahí.

	Organización				Sub-organización
Capacidad	owner	buyer	monitor	integration	sub_owner	sub_monitor
Ver posiciones de sus tags	✓	—	✓	—	✓	✓
Crear órdenes	✓	✓	—	—	—	—
Ver estado de órdenes	✓	✓	—	—	—	—
API de integración y webhooks	✓	—	—	✓	✓	—
Gestionar roles	buyer · monitor · integration, y los de sus sub-orgs	—	—	—	sub_owner · sub_monitor de su sub-org	—

Una sub-organización no compra: sus roles sólo ven y gestionan lo de esa sub-organización. owner y monitor de la organización ven también los tags de todas sus sub-organizaciones.

Usuarios y roles de tu organización

Escoge en el mapa dónde trabajar: ahí mismo ves a su gente y le asignas roles.

Mapa de la organización

Escoge una organización o una sub-organización: ahí se cargan sus usuarios y ahí se asignan los roles.

Añadir organización

Cargando organizaciones…

Usuarios del Proveedor

Miembros con acceso al scope suntech y sus roles asignados.

Flujo de asignación de roles

01 Seguridad

Login de usuario

POST /security/auth/login
Obtén el accessToken con el que se autentican todas las llamadas de membresías. Dura 10 minutos; el renewToken, 7 días.

→accessToken

Request / Response

{ email, password } accessToken · renewToken · expiresIn: 600

Ver autenticación →

02 Membresías

Ver mis orgs y roles

GET /memberships/me
Descubre tu organizationId, tus roles en cada organización y si tienes acceso suntech. Necesario antes de asignar.

→organizationIdroles[]

Request / Response

Bearer {accessToken} organizations[{ organizationId, organizationName, roles[] }] · suntech · isSuperuser

Ver las macros de /memberships →

03 Membresías

Asignar rol

POST /memberships/assign-role
Concede un rol a uno o varios usuarios por correo; quien no tenga cuenta la recibe, con su correo de bienvenida (wasNew). Responde 200 aunque falle con alguno: revisa errors[]. Scope dealer requiere organizationId; scope suntech no.

→granted[]errors[]

Request / Response

{ scope, role, organizationId?, users:[{ userEmail, userName?, phone? }] } granted[{ …, wasNew }] · errors[{ error }]

Ver las macros de /memberships →

04 Membresías

Revocar rol

POST /memberships/revoke
Quita un rol a un usuario; sus otros roles se quedan. Es idempotente: revocar un rol que no tiene también responde revoked: true.

→revoked: true

Request / Response

{ scope, role, organizationId?, userId } { userId, scope, organizationId, role, revoked: true }

Ver las macros de /memberships →

05 Membresías

Listar miembros

GET /memberships
Lista los usuarios y sus roles en una organización o en el proveedor. La pueden ver el owner (también en sus sub-orgs), el sub_owner en la suya, un superusuario y el owner de Tagora.

→members[]

Request / Response

?scope=dealer&organizationId= · ?scope=suntech { scope, organizationId, members[{ userId, email, name, roles[] }] }

Ver las macros de /memberships →

0. Preparación — login + variables

Obtén el accessToken y define las variables base reutilizables en todos los ejemplos.

El Proveedor

Roles sobre el proveedor: owner storekeeper sales — asignados con /memberships (scope suntech, sin organizationId).

owner

1. Owner del Proveedor — ve todos los tags

GET /suntech/devices devuelve los dispositivos agrupados por dealer (con bucket unassigned para inventario sin org). El owner además ve todas las posiciones vía el grant comodín asset:* viewer provider:#owner.

storekeeper

2. Almacenista — todo lo de envíos. Sin mapa

Recibe el correo de la orden y la surte como un todo (advance status + reporta seriales). Scopeado a las órdenes del proveedor. No ve posiciones (/live responde 403).

sales

3. Vendedores — órdenes a nombre de un Dealer

POST /orders. Puede ordenar para cualquier dealer. Solo-alta: no ve ni cambia el estado de las órdenes (eso es del storekeeper/owner). Manda exactamente uno de organizationId / organizationName. Cantidad múltiplo de 100.

solo owner

4. Solo el Owner del Proveedor ve posiciones

/live, /historical y /sse chequean viewer por asset. El owner lo cumple vía el comodín. storekeeper y sales no tienen ningún grant de posiciones → 403.

Distribuidores (Dealer) — minimizar permisos (fail-closed)

Roles sobre la org dealer: owner | buyer | monitor | integration. Un usuario sin rol no puede hacer nada (fail-closed) — el cliente final no tiene acceso hasta que un owner le conceda un rol.

owner

5. Owner del Dealer — crea usuarios de todo

El owner es superset (puede todo lo de buyer/monitor/integration). Da de alta a los usuarios con la macro /memberships/grant (find-or-create por email + correo de alta).

Roles dealer válidos para el owner: buyer | monitor | integration. Conceder owner está restringido a superuser / tagora (anti-escalada).

buyer

5b. Comprador — realiza pedidos para su org

Puede crear órdenes para su propia organización. No gestiona roles ni ve posiciones.

integration

6. Integración — credenciales de API

Al conceder role:"integration", la macro acuña api-key + secret (el secret se devuelve una sola vez). Esos usuarios consumen /integration/* (login api-key → scope=integration).

monitor

7. Monitorista — ve posiciones de sus tags

monitor → viewer está cableado en el motor; los grants por asset apuntan al userset #viewer de la org. El monitor alcanza las posiciones de su org (no de otras).

sin rol

8. Cliente final (sin rol) — no puede nada

Un usuario logueado pero sin tupla ReBAC falla cerrado en todo: /live → 403, /orders → 403, /suntech/* → 403, /memberships/grant → 403. No hay acción que pueda ejecutar hasta que un owner le conceda un rol.

Macros de gestión de roles — /memberships

Componen los servicios atómicos (users + permissions + integration). Los owners de cada nivel administran sus propios sub-roles; conceder/revocar owner es sólo superuser/tagora.

Método y ruta	Para qué
GET /memberships/me	mis orgs + roles + nivel (post-login)
POST /memberships/assign-role ⭐	un rol, mismo scope/org, lista de usuarios — el macro recomendado para owners
POST /memberships/grant	conceder un rol a un usuario (find-or-create por userEmail, o userId)
POST /memberships/grant-bulk	varios roles en una sola llamada (distintos scopes/orgs/roles permitidos)
POST /memberships/revoke	revocar un rol (editar = revocar + conceder el nuevo)
GET /memberships?scope=&organizationId=	listar miembros + roles de una org/provider (solo owner/su/tagora)
POST /memberships/dealer	marcar/quitar una org como dealer del proveedor

¿Cómo "editar" un rol? No hay PATCH de rol: revoca el rol anterior y concede el nuevo. grant/revoke son idempotentes (granted/revoked=false si no hubo cambio), así que es seguro repetirlos.

Autorización (callback authorize en el router)

superuser / tagora owner → todo.
owner del dealer → conceder/revocar buyer|monitor|integration en su org.
owner del proveedor → conceder/revocar storekeeper|sales y manejar links de dealer.
conceder/revocar owner → sólo superuser / tagora.