Get User Roles List

Overview

Retrieves a list of all user roles available in your account, including default roles (Manager, Admin, Viewer) and any custom roles you’ve created. Each role includes its permissions and access levels.

Purpose

Role Management

View Available Roles: See all roles in your account
Understand Permissions: Review what each role can do
Plan User Access: Choose appropriate roles when adding users
Custom Role Reference: Reference custom roles you’ve created

Default Roles

Manager (ID: 1): Can create, edit, and manage QR codes
Admin (ID: 2): Full access including user management
Viewer (ID: 3): Read-only access to QR codes and analytics

Response Structure

The response returns an array of access level objects, each containing:

Field	Type	Description
`id`	integer	Unique role identifier
`name`	string	Role name (e.g., “Manager”, “Admin”, “Viewer”)
`permissions`	array	List of permissions for this role
`is_custom`	boolean	Whether this is a custom role or default

Permission Object Structure

Each permission in the permissions array contains:

Field	Type	Description
`id`	integer	Permission identifier
`code`	string	Permission code (e.g., “QR_CODE_CAN_ADD”)
`name`	string	Human-readable permission name
`description`	string	Detailed permission description
`is_boolean`	boolean	Whether this is a boolean permission

Examples

Get All User Roles

curl -X GET "https://management.scanova.io/multi-users/access-levels/" \
  -H "Authorization: YOUR_API_KEY"

Response Example

[
  {
    "id": 1,
    "name": "Manager",
    "permissions": [
      {
        "id": 22,
        "code": "QR_CODE_CAN_ADD",
        "name": "Can Add QR Code",
        "description": "Can add QR Code",
        "is_boolean": true
      },
      {
        "id": 23,
        "code": "QR_CODE_CAN_VIEW",
        "name": "Can view QR Code",
        "description": "Can view QR Code",
        "is_boolean": true
      },
      {
        "id": 24,
        "code": "QR_CODE_CAN_EDIT",
        "name": "Can edit QR Code",
        "description": "Can edit QR Code",
        "is_boolean": true
      },
      {
        "id": 26,
        "code": "QR_CODE_CAN_DOWNLOAD",
        "name": "Can download QR code",
        "description": "Can download QR Code",
        "is_boolean": true
      },
      {
        "id": 1,
        "code": "ANALYTICS_CAN_VIEW",
        "name": "Analytics Can View",
        "description": "Can view analytics",
        "is_boolean": true
      }
    ],
    "is_custom": false
  },
  {
    "id": 2,
    "name": "Admin",
    "permissions": [
      {
        "id": 22,
        "code": "QR_CODE_CAN_ADD",
        "name": "Can Add QR Code",
        "description": "Can add QR Code",
        "is_boolean": true
      },
      {
        "id": 25,
        "code": "QR_CODE_CAN_DELETE",
        "name": "Can Delete QR Code",
        "description": "Can delete QR code",
        "is_boolean": true
      },
      {
        "id": 18,
        "code": "SHARED_USER_CAN_VIEW",
        "name": "Can view shared user",
        "description": "Can view user",
        "is_boolean": true
      },
      {
        "id": 19,
        "code": "SHARED_USER_CAN_ADD",
        "name": "Can add shared user",
        "description": "Can add user",
        "is_boolean": true
      }
    ],
    "is_custom": false
  },
  {
    "id": 3,
    "name": "Viewer",
    "permissions": [
      {
        "id": 23,
        "code": "QR_CODE_CAN_VIEW",
        "name": "Can view QR Code",
        "description": "Can view QR Code",
        "is_boolean": true
      },
      {
        "id": 1,
        "code": "ANALYTICS_CAN_VIEW",
        "name": "Analytics Can View",
        "description": "Can view analytics",
        "is_boolean": true
      }
    ],
    "is_custom": false
  }
]

Common Permission Codes

QR Code Permissions

QR_CODE_CAN_ADD: Can create new QR codes
QR_CODE_CAN_VIEW: Can view QR codes
QR_CODE_CAN_EDIT: Can edit existing QR codes
QR_CODE_CAN_DELETE: Can delete QR codes
QR_CODE_CAN_DOWNLOAD: Can download QR codes
QR_CODE_CAN_EXPORT: Can export QR codes

Analytics Permissions

ANALYTICS_CAN_VIEW: Can view analytics data
ANALYTICS_CAN_EXPORT: Can export analytics
ANALYTICS_CAN_EXPORT_RAW: Can export raw analytics data
ANALYTICS_CAN_VIEW_ALL_USERS: Can view analytics for all users

User Management Permissions

SHARED_USER_CAN_VIEW: Can view shared users
SHARED_USER_CAN_ADD: Can add new users
SHARED_USER_CAN_EDIT: Can edit user roles
SHARED_USER_CAN_DELETE: Can remove users

Lead Generation Permissions

LEAD_GENERATION_CAN_ADD: Can create lead lists
LEAD_GENERATION_CAN_EDIT: Can edit lead lists
LEAD_GENERATION_CAN_DELETE: Can delete lead lists
LEAD_GENERATION_ENTRY_CAN_VIEW: Can view lead entries

Custom Domain Permissions

CUSTOM_DOMAIN_CAN_VIEW: Can view custom domains
CUSTOM_DOMAIN_CAN_ADD: Can add custom domains
CUSTOM_DOMAIN_CAN_DELETE: Can delete custom domains

Integration Examples

JavaScript - Fetch and Display Roles

async function getUserRoles() {
  try {
    const response = await fetch('https://management.scanova.io/multi-users/access-levels/', {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY'
      }
    });
    
    if (response.ok) {
      const roles = await response.json();
      
      // Display roles in a dropdown
      const roleSelect = document.getElementById('roleSelect');
      roles.forEach(role => {
        const option = document.createElement('option');
        option.value = role.id;
        option.textContent = `${role.name} (${role.is_custom ? 'Custom' : 'Default'})`;
        roleSelect.appendChild(option);
      });
      
      return roles;
    } else {
      throw new Error('Failed to fetch roles');
    }
  } catch (error) {
    console.error('Error fetching roles:', error);
    return [];
  }
}

// Usage
getUserRoles().then(roles => {
  console.log('Available roles:', roles);
});

Python - Get Roles and Permissions

import requests

def get_user_roles():
    url = "https://management.scanova.io/multi-users/access-levels/"
    headers = {"Authorization": "YOUR_API_KEY"}
    
    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        
        roles = response.json()
        
        # Print role information
        for role in roles:
            print(f"Role: {role['name']} (ID: {role['id']})")
            print(f"Custom: {role['is_custom']}")
            print("Permissions:")
            for permission in role['permissions']:
                print(f"  - {permission['name']}: {permission['description']}")
            print()
        
        return roles
        
    except requests.exceptions.RequestException as e:
        print(f"Error fetching roles: {e}")
        return []

# Usage
roles = get_user_roles()

PHP - Display Role Options

<?php
function getUserRoles() {
    $url = "https://management.scanova.io/multi-users/access-levels/";
    $headers = [
        "Authorization: YOUR_API_KEY"
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        $roles = json_decode($response, true);
        
        // Generate HTML select options
        echo "<select name='role'>";
        foreach ($roles as $role) {
            $custom = $role['is_custom'] ? ' (Custom)' : ' (Default)';
            echo "<option value='{$role['id']}'>{$role['name']}{$custom}</option>";
        }
        echo "</select>";
        
        return $roles;
    } else {
        echo "Error fetching roles";
        return [];
    }
}

// Usage
$roles = getUserRoles();
?>

Use Cases

User Management Interface

Role Selection: Populate dropdown menus with available roles
Permission Display: Show what each role can do
Access Control: Validate user permissions before actions
Role Comparison: Compare different roles and their capabilities

API Integration

Dynamic Role Assignment: Use role IDs when adding users
Permission Checking: Verify user permissions before operations
Role Validation: Ensure valid roles are used in requests
Access Control: Implement role-based access control

Administrative Tools

Role Audit: Review all roles and their permissions
Permission Analysis: Understand what each role can access
Custom Role Management: Manage custom roles and permissions
Access Planning: Plan user access based on available roles

This endpoint is essential for understanding the available roles and permissions in your account. Use this information when adding new users or planning access control strategies.

Default roles (Manager, Admin, Viewer) cannot be modified, but you can create custom roles with specific permission combinations through the Scanova dashboard.

Authorizations

Authorization

string

header

required

API key authentication. Enter your API key directly in the Authorization header.

Response

List of user roles and permissions

integer

Access level ID

Example:

1

name

string

Access level name

Example:

"Manager"

permissions

object[]

List of permissions for this access level

Show child attributes

is_custom

boolean

Whether this is a custom role or default role

Example:

false

Getting Started

Reference

QR Code Management

Lead List Management

User Management

Analytics & Reporting

Overview

Purpose

Role Management

Default Roles

Response Structure

Permission Object Structure

Examples

Get All User Roles

Response Example

Common Permission Codes

QR Code Permissions

Analytics Permissions

User Management Permissions

Lead Generation Permissions

Custom Domain Permissions

Integration Examples

JavaScript - Fetch and Display Roles

Python - Get Roles and Permissions

PHP - Display Role Options

Use Cases

User Management Interface

API Integration

Administrative Tools

Authorizations

Response

Getting Started

Reference

QR Code Management

Lead List Management

User Management

Analytics & Reporting

​Overview

​Purpose

​Role Management

​Default Roles

​Response Structure

​Permission Object Structure

​Examples

​Get All User Roles

​Response Example

​Common Permission Codes

​QR Code Permissions

​Analytics Permissions

​User Management Permissions

​Lead Generation Permissions

​Custom Domain Permissions

​Integration Examples

​JavaScript - Fetch and Display Roles

​Python - Get Roles and Permissions

​PHP - Display Role Options

​Use Cases

​User Management Interface

​API Integration

​Administrative Tools

Authorizations

Response

Overview

Purpose

Role Management

Default Roles

Response Structure

Permission Object Structure

Examples

Get All User Roles

Response Example

Common Permission Codes

QR Code Permissions

Analytics Permissions

User Management Permissions

Lead Generation Permissions

Custom Domain Permissions

Integration Examples

JavaScript - Fetch and Display Roles

Python - Get Roles and Permissions

PHP - Display Role Options

Use Cases

User Management Interface

API Integration

Administrative Tools