Organizations & Roles
RIoT is a multi-tenant platform with role-based access control (RBAC). Every user, device, and data point belongs to exactly one tenant. Organizations connect users to tenants and define what each user can do within that boundary.
This guide covers tenant isolation, organization membership, the role hierarchy, and how to invite and manage members.
Multi-Tenancy
A tenant is the top-level data isolation boundary in RIoT. All resources -- locations, areas, devices, sensor readings, exports -- belong to a single tenant. Cross-tenant access is impossible by design.
Isolation guarantees:
- Every database query is scoped to the active tenant. Backend queries always filter by
tenant_idbefore applying any other criteria. - Users can only see and interact with resources that belong to their active organization's tenant.
- Devices are registered to a single tenant and can only report data to that tenant.
- API responses never leak data from other tenants, even in error messages.
Tenants are created automatically when a user registers and creates an organization. There is no way to create a tenant without an organization, and no way to access a tenant without membership.
Organizations
An organization is the entity that connects users to a tenant. When you create an organization, a corresponding tenant is created and you become its owner.
Membership
Users interact with tenants through organization memberships. Each membership links a user to an organization with a specific role.
- A user can belong to multiple organizations, each with a different role.
- Only one organization is active at a time. The active organization determines which tenant's data the user sees in the dashboard and API.
- Each user can create one organization. Additional organizations are joined via invitation.
Switching Organizations
Use the organization switcher in the dashboard header to change your active organization. Switching is instant -- the session updates to reflect the new tenant context, and all queries re-scope to the selected organization's data.
When you switch organizations, your role changes to match your membership in the target organization. An org_admin in one organization may be a user in another.
Via the API, switch organizations by calling:
POST /v1/organizations/switch
{ "organization_id": <id> }
The response confirms the new active organization and your role within it.
Roles & Permissions
RIoT uses a fixed role hierarchy scoped to each organization. Roles are assigned per-membership -- a user can hold different roles in different organizations.
There are four organization-level roles and one platform-level flag:
| Role | Scope | Description |
|---|---|---|
super_admin | Platform | Full access to all platform-wide resources (e.g., global sensor types catalog). Set via the is_super_admin flag on the user, not an organization role. |
org_owner | Organization | Full control within the organization. Automatically assigned to the user who created the organization. One owner per organization. |
org_admin | Organization | Can manage devices, locations, configurations, and invite or manage users. Cannot transfer ownership or delete the organization. |
field_admin | Organization | Can manage devices and locations. No access to user management or invitations. |
user | Organization | View-only access to data and dashboards. Can create data exports. |
Detailed Permission Matrix
| Action | super_admin | org_owner | org_admin | field_admin | user |
|---|---|---|---|---|---|
| View dashboard and sensor data | Yes | Yes | Yes | Yes | Yes |
| Create data exports | Yes | Yes | Yes | Yes | Yes |
| Register and manage devices | Yes | Yes | Yes | Yes | -- |
| Create and edit locations/areas | Yes | Yes | Yes | Yes | -- |
| Push device configurations | Yes | Yes | Yes | Yes | -- |
| Send device commands | Yes | Yes | Yes | Yes | -- |
| Invite users to organization | Yes | Yes | Yes | -- | -- |
| View and revoke invitations | Yes | Yes | Yes | -- | -- |
| Change member roles | Yes | Yes | Yes | -- | -- |
| Remove members | Yes | Yes | Yes | -- | -- |
| Manage organization settings | Yes | Yes | -- | -- | -- |
| Manage global sensor types | Yes | -- | -- | -- | -- |
Notes:
super_adminis a platform-level flag, not an organization role. It grants access to global resources that exist outside any single tenant, such as the shared sensor types catalog.org_owneris assigned automatically at organization creation and cannot be transferred or assigned via invitation. The owner's role cannot be changed by anyone.org_admincan manage other members but cannot promote anyone toorg_owneror change the owner's role.- Assignable roles for invitations and role changes are limited to:
org_admin,field_admin, anduser.
Inviting Users
Only org_owner and org_admin roles can create invitations.
Creating an Invitation
- Navigate to the Organization page.
- Select Create Invitation.
- Choose a role to assign to the invitee (
org_admin,field_admin, oruser). - Set the expiration period (1, 7, 14, or 30 days).
- Optionally set a max uses limit. Leave blank for unlimited uses.
- Select Create Invitation. The platform generates a unique invite link.
Copy the invite link and share it with the intended recipient. The link is shown only once -- if lost, revoke the invitation and create a new one.
Invitation Details
Each invitation includes:
| Field | Description |
|---|---|
| Role | The role assigned when the invitation is accepted. |
| Expiration | When the invitation link stops working. |
| Max uses | How many times the link can be used. null means unlimited. |
| Use count | How many times the link has been used so far. |
| Status | Whether the invitation is active, expired, or revoked. |
Accepting an Invitation
Recipients open the invite link in their browser. The link follows the format:
https://<domain>/invite/<token>
The landing page displays the organization name, assigned role, and who sent the invitation (email is partially obfuscated for privacy).
- If the recipient already has an account, they sign in and are added to the organization with the specified role.
- If the recipient does not have an account, they register first, then accept the invitation.
After accepting, the recipient's active organization automatically switches to the newly joined organization.
Revoking an Invitation
To revoke a pending invitation:
- Navigate to the Organization page.
- Find the invitation in the invitations list.
- Select Revoke.
Revoked invitations cannot be reactivated. Create a new invitation if needed.
Security
Invitation tokens are stored as SHA-256 hashes in the database -- the raw token is never persisted. Tokens use 256 bits of cryptographic entropy prefixed with riot_inv_. Acceptance is protected by row-level locking to enforce max_uses limits under concurrent requests.
Managing Members
Viewing Members
All organization members can view the member list. Navigate to the Organization page to see every member, their role, whether they are the owner, and when they joined.
Changing Roles
org_owner and org_admin can change a member's role.
- Navigate to the Organization page.
- Find the member in the members list.
- Select a new role from the role dropdown.
Constraints:
- The owner's role cannot be changed.
- No one can be promoted to
org_owner-- ownership is set at organization creation. - Assignable roles are
org_admin,field_admin, anduser. - Role changes take effect on the member's next API request. Active sessions are updated dynamically.
Removing Members
org_owner and org_admin can remove members from the organization.
- Navigate to the Organization page.
- Find the member in the members list.
- Select Remove.
When a member is removed:
- Their organization membership is deleted.
- All active sessions scoped to that organization are cleared. The removed user loses access immediately.
- The user's account is not deleted -- they retain access to any other organizations they belong to.
Self-removal: Any non-owner member can leave an organization voluntarily. This follows the same process as removal by an admin.
The organization owner cannot be removed. Ownership is permanent and cannot be transferred.