Scopes & Permissions

IPCom v5.0.0 uses a scope-based authorization system to control access to API endpoints and resources.

Overview

After authentication, each user has a set of scopes that determine which API endpoints they can access. Scopes provide fine-grained control over user permissions.

Available Scopes

settings

• Purpose: System configuration management
• Endpoints:
  • GET /api/settings - View system settings
  • PUT /api/settings - Modify system configuration
• Description: Allows users to view and modify system-wide settings including database configuration, API settings, receivers, outputs, and general configuration.

users

• Purpose: User account management
• Endpoints:
  • GET /api/users - List user accounts
  • POST /api/users - Create new users
  • PUT /api/users - Update user accounts
  • DELETE /api/users - Remove users
• Description: Provides access to user management functions including creating, updating, and deleting user accounts.

events

• Purpose: Event monitoring and management
• Endpoints:
  • GET /api/events - View system events
  • GET /api/events/filters - Access event filtering
  • WebSocket /events - Real-time event streaming
• Description: Allows access to system events, event history, and real-time event monitoring.

objects

• Purpose: Device and object management
• Endpoints:
  • GET /api/objects - View device objects
  • DELETE /api/objects - Delete all objects
  • DELETE /api/object - Delete single object
  • PUT /api/oid-override - Set OID override for devices
  • GET /api/is-connected - Check device connection status
• Description: Provides access to device management, object monitoring, device configuration, and OID override functionality.

device_control

• Purpose: Device control and command execution
• Endpoints:
  • POST /api/control-device - Send commands to devices
  • POST /api/config-device - Configure device settings
• Description: Allows sending control commands and configuration updates to devices. Required for remote device operation, management, and configuration.

omit_mpass

• Purpose: Bypass cloud access code requirements
• Endpoints:
  • Used with POST /api/control-device and POST /api/config-device
• Description: Special scope that allows users to perform certain operations without requiring clooud access code verification. Should be used carefully and only for trusted automated systems.

restart_services

• Purpose: Service management and restart operations
• Endpoints:
  • GET /api/restart-services - Restart all receiver and output services
• Description: Allows restarting system services to apply configuration changes without full system restart. Should be restricted to administrators and maintenance personnel due to potential service interruption.

turnoff_receiver

• Purpose: System shutdown and termination
• Endpoints:
  • POST /api/shutdown-receiver - Shutdown the entire IPCom service
• Description: Allows complete system shutdown and service termination. This is a critical operation that should be highly restricted to senior administrators only due to complete service unavailability.

license

• Purpose: License management and activation
• Endpoints:
  • POST /api/license - Activate system license with provided license key
• Description: Allows activation of system licenses using valid license keys. License activation causes immediate system shutdown and requires manual restart unless configured as a service. This is a critical operation that should be restricted to senior administrators and license managers only.

Scope Assignment

Scopes are assigned to users in their user configuration:

{
  "users": [
    {
      "id": 1,
      "login": "admin",
      "password": "secure_password",
      "scopes": ["settings", "users", "events", "objects"],
      "token_time": 1440
    },
    {
      "id": 2,
      "login": "operator",
      "password": "operator_pass",
      "scopes": ["events", "objects"],
      "token_time": 480
    },
    {
      "id": 3,
      "login": "viewer",
      "password": "viewer_pass",
      "scopes": ["events"],
      "token_time": 240
    }
  ]
}

Common Permission Patterns

Administrator

"scopes": ["settings", "users", "events", "objects", "device_control", "restart_services"]

• Full system access including device control and service management
• Can manage all aspects of the system except shutdown
• Suitable for system administrators

Senior Administrator

"scopes": ["settings", "users", "events", "objects", "device_control", "restart_services", "turnoff_receiver"]

• Complete system access including critical shutdown operations
• Can perform all administrative functions including system termination
• Suitable for senior administrators and emergency response personnel

Device Operator

"scopes": ["events", "objects", "device_control"]

• Monitor events and devices
• Can control and command devices
• Cannot modify system settings or users
• Suitable for control room operators

Automated System

"scopes": ["device_control", "omit_mpass", "objects"]

• Can control devices without cloud access code
• Access to device information
• Suitable for automated monitoring and control systems

Operator

"scopes": ["events", "objects"]

• Monitor events and devices
• Cannot control devices or modify settings
• Suitable for monitoring dashboards

Viewer

"scopes": ["events"]

• Read-only access to events
• Cannot modify anything
• Suitable for monitoring dashboards

Manager

"scopes": ["users", "events", "objects", "restart_services"]

• Can manage users and monitor system
• Can restart services for maintenance
• Cannot change system configuration
• Suitable for team managers and maintenance personnel

Authorization Flow

1. Login: User provides credentials
2. Token Generation: JWT token includes user's scopes
3. API Request: Client sends token with request
4. Scope Validation: Server checks if user has required scope
5. Access Decision: Grant or deny access based on scopes

Error Responses

Missing Authentication

HTTP/1.1 401 Unauthorized

NOT_LOGGED_IN

Insufficient Permissions

HTTP/1.1 403 Forbidden

FORBIDDEN

Resource Visibility

Some scopes also control which resources a user can see:

Receiver Visibility

Users can have restricted access to specific receivers:

{
  "id": 2,
  "login": "operator",
  "visible_receivers": {
    "all": false,
    "custom": [1, 3, 5]
  }
}

• "all": true - User can see all receivers
• "all": false, "custom": [1,3,5] - User can only see receivers 1, 3, and 5

Best Practices

Principle of Least Privilege

• Only assign scopes that users actually need
• Regularly review and audit user permissions
• Use specific scope combinations for different roles

Token Security

• Use appropriate token expiration times
• Shorter expiration for high-privilege accounts
• Implement token refresh for long-running applications

Scope Validation

• Always check scope requirements in your client applications
• Handle permission errors gracefully
• Provide clear feedback when access is denied

Examples

Check Required Scope in Code

async function getSettings(client) {
  try {
    const response = await client.apiCall('/settings');
    return await response.json();
  } catch (error) {
    if (error.status === 403) {
      console.error('User lacks "settings" scope');
      // Redirect to access request page
    }
    throw error;
  }
}

Conditional UI Based on Scopes

// Decode JWT to check user scopes
function getUserScopes(token) {
  const payload = JSON.parse(atob(token.split('.')[1]));
  return payload.scopes || [];
}

const userScopes = getUserScopes(authToken);

// Show/hide UI elements based on scopes
if (userScopes.includes('settings')) {
  showSettingsMenu();
}

if (userScopes.includes('users')) {
  showUserManagement();
}

Support

For questions about scope configuration or permission issues:

• Review the API Reference for endpoint details
• Contact support with specific use cases