Roles and Access Management

Haltian IoT Platform implements Role-Based Access Control (RBAC) for both user accounts and API access, providing fine-grained permission management across the platform.

Overview

The platform implements a hierarchical RBAC system with five distinct roles, each designed for specific use cases and responsibilities. Access control operates at two primary scopes: Organization and Space, allowing fine-grained permission management.

User Roles

The platform provides five predefined roles with increasing levels of access:

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#73f9c1','primaryTextColor':'#143633','primaryBorderColor':'#143633','secondaryColor':'#ff8862','tertiaryColor':'#f6fafa','lineColor':'#143633','textColor':'#143633','edgeLabelBackground':'#ffffff'}}}%%
graph TD
    A([System Admin]) -->|Full system access| B([Platform])
    C([Organization Manager]) -->|Organization scope| D([Organization])
    E([Space Designer]) -->|Space scope| F([Spaces])
    G([Asset Installer]) -->|Asset scope| H([Assets/Devices])
    I([Data Viewer]) -->|Read-only| J([Data])
    
    D -->|Contains| F
    F -->|Contains| H
    
    style A fill:#ff8862,stroke:#143633,stroke-width:3px,color:#fff
    style B fill:#f6fafa,stroke:#143633,stroke-width:2px,color:#143633
    style C fill:#ff8862,stroke:#143633,stroke-width:2px,color:#fff
    style D fill:#f6fafa,stroke:#143633,stroke-width:2px,color:#143633
    style E fill:#73f9c1,stroke:#143633,stroke-width:2px,color:#143633
    style F fill:#f6fafa,stroke:#143633,stroke-width:2px,color:#143633
    style G fill:#73f9c1,stroke:#143633,stroke-width:2px,color:#143633
    style H fill:#f6fafa,stroke:#143633,stroke-width:2px,color:#143633
    style I fill:#cfe3e0,stroke:#143633,stroke-width:2px,color:#143633
    style J fill:#f6fafa,stroke:#143633,stroke-width:2px,color:#143633

Role Descriptions

1. System Admin

• Scope: Entire platform
• Purpose: System-wide administration
• Permissions: Full access to all organizations and system configuration
• Use Case: Haltian platform administrators

2. Organization Manager

• Scope: Organization-wide
• Purpose: Manage organization users, devices, and structural data
• Permissions:
  • View all organization data (devices, tags, structures)
  • Manage user accounts within the organization
  • Create accounts for installers and other roles
  • Manage keywords used in the organization
  • Site/building/floor/zone level management
  • Full GraphQL API access (read/write)
• Use Case: Organization administrators, facility managers

3. Space Designer

• Scope: Specific spaces (or organization-wide if assigned at org level)
• Purpose: Manage organization infrastructure
• Permissions:
  • View all organization data (devices, tags, structures)
  • Site/building/floor/zone level management
  • Limited write access compared to Manager
• Use Case: Architects, space planners, design teams

4. Asset Installer

• Scope: Site-level assets and devices
• Purpose: Install and maintain devices/tags at site level
• Permissions:
  • View, add, and edit site-level devices and tags
  • Limited to assigned sites
  • Cannot manage users or organization structure
• Use Case: Field technicians, installation teams

5. Data Viewer

• Scope: Site-level data (read-only)
• Purpose: View site-level devices and measurements
• Permissions:
  • Read-only access to site-level devices and tags
  • Limited GraphQL API access (queries only)
  • Cannot modify any data
• Use Case: Dashboard users, report viewers, stakeholders

Access Control Scopes

The RBAC system operates at two distinct scopes:

Organization Scope

When a user is assigned a role at the organization scope:

• The user receives that role’s permissions for every space within the organization
• Access is automatically granted to all current and future spaces
• Suitable for organization-wide administrators and managers

Space Scope

When a user is assigned a role at the space scope:

• The user receives that role’s permissions only for specified spaces
• Access is limited to explicitly assigned spaces within the organization
• Suitable for site-specific personnel (installers, site managers)

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#73f9c1','primaryTextColor':'#143633','primaryBorderColor':'#143633','secondaryColor':'#ff8862','tertiaryColor':'#f6fafa','lineColor':'#143633','textColor':'#143633','edgeLabelBackground':'#ffffff'}}}%%
graph LR
    A([User]) -->|Organization Scope| B([Organization])
    B --> C([Space 1])
    B --> D([Space 2])
    B --> E([Space 3])
    
    F([User]) -->|Space Scope| G([Space 2])
    
    style A fill:#f6fafa,stroke:#143633,stroke-width:2px,color:#143633
    style B fill:#ff8862,stroke:#143633,stroke-width:2px,color:#fff
    style C fill:#cfe3e0,stroke:#143633,color:#143633
    style D fill:#cfe3e0,stroke:#143633,color:#143633
    style E fill:#cfe3e0,stroke:#143633,color:#143633
    style F fill:#f6fafa,stroke:#143633,stroke-width:2px,color:#143633
    style G fill:#73f9c1,stroke:#143633,stroke-width:2px,color:#143633

API Authentication & Authorization

User Account Authentication

The Service API (GraphQL) uses RBAC for user authentication:

1. Login with email, password, and organization name
2. Receive access token (valid 15 minutes) and refresh token (valid 12 hours)
3. Include access token in HTTP header: Authorization: Bearer {token}
4. API introspection adapts to user’s role (Manager sees full API, Viewer sees limited queries)

Authentication Flow:

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#73f9c1','primaryTextColor':'#143633','primaryBorderColor':'#143633','secondaryColor':'#ff8862','tertiaryColor':'#f6fafa','lineColor':'#143633','textColor':'#143633','actorBkg':'#f6fafa','actorBorder':'#143633','actorTextColor':'#143633','noteBkgColor':'#cfe3e0','noteBorderColor':'#143633','noteTextColor':'#143633'}}}%%
sequenceDiagram
    participant C as Client
    participant A as API
    
    note over C,A: Initial Login
    C->>A: LoginMutation($email, $password, $organizationName)
    A-->>C: accessToken (15min), refreshToken (12h), organizationId
    
    note over C,A: API Requests (with role-based permissions)
    C->>A: Query/Mutation + Bearer Token
    A-->>C: Response (filtered by role)
    
    note over C,A: Token Refresh (before expiry)
    C->>A: RefreshMutation($refreshToken, $organizationId)
    A-->>C: New accessToken, refreshToken
    
    note over C,A: Logout
    C->>A: LogoutMutation()
    A-->>C: Session terminated

API Key Authentication

For machine-to-machine integrations and MQTT access:

• API Keys provide managed access without user accounts
• Configured via Studio application by Organization Manager
• Not tied to specific user roles
• Can be assigned to specific spaces with keyword permissions
• Primary use case: MQTT Stream API subscriptions

API Key Scope:

API Access by Role

Different APIs have different authorization models:

GraphQL API Access

The GraphQL API adapts its schema based on the authenticated user’s role:

• Manager role: Full API access (all queries and mutations)
• Designer role: Read access + limited write operations
• Installer role: Site-level device management
• Viewer role: Limited to read-only queries

Practical Examples

Example 1: Organization Manager

Scenario: Sarah manages all IoT devices across multiple office buildings.

• Role: Organization Manager
• Scope: Organization-wide
• Permissions:
  • Create user accounts for installers at each building
  • Configure all devices across all sites
  • Access full GraphQL API for reporting
  • Manage API keys for MQTT integrations

Example 2: Space Designer

Scenario: John designs floor layouts and zones for Building A only.

• Role: Space Designer
• Scope: Space-level (Building A)
• Permissions:
  • View and edit floor plans for Building A
  • Define zones and rooms within Building A
  • View all devices in Building A
  • Cannot access other buildings or manage users

Example 3: Asset Installer

Scenario: Maria installs and maintains sensors across assigned sites.

• Role: Asset Installer
• Scope: Site-level (Buildings A and C)
• Permissions:
  • Add new devices at assigned sites
  • Update device configurations and locations
  • View device status and measurements
  • Cannot create user accounts or modify floor plans

Example 4: Data Viewer

Scenario: Tom monitors dashboards showing occupancy and environmental data.

• Role: Data Viewer
• Scope: Site-level (read-only)
• Permissions:
  • View device measurements and sensor data
  • Access read-only GraphQL queries
  • View floor plans and device locations
  • Cannot modify any configuration

Best Practices

Role Assignment

1. Principle of Least Privilege: Assign the minimum role required for the user’s responsibilities
2. Scope Appropriately: Use space-level roles for site-specific personnel
3. Regular Audits: Review user roles and permissions periodically
4. Separation of Duties: Use different roles for different teams (designers vs. installers)

API Key Management

1. Dedicated Keys: Create separate API keys for each integration or service
2. Space Limiting: Restrict API keys to specific spaces when possible
3. Keyword Filtering: Use keyword permissions to limit data access
4. Rotation: Regularly rotate API keys for security
5. Monitoring: Track API key usage and disable unused keys

Security Considerations

• Token Expiration: Access tokens expire after 15 minutes; use refresh tokens to maintain sessions
• Role Changes: Role or permission changes take effect on next login (new token required)
• Space Access: Removing a user from a space immediately revokes their access to that space’s data
• API Key Security: Treat API keys as secrets; never commit them to version control