> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get User Roles List

> Get a list of all user roles available in your account. This includes default roles (Manager, Admin, Viewer) as well as custom created roles with their permissions.

## 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**

```bash theme={null}
curl -X GET "https://management.scanova.io/multi-users/access-levels/" \
  -H "Authorization: YOUR_API_KEY"
```

### **Response Example**

```json theme={null}
[
  {
    "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**

```javascript theme={null}
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**

```python theme={null}
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 theme={null}
<?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

<Note>
  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.
</Note>

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


## OpenAPI

````yaml GET /multi-users/access-levels/
openapi: 3.0.0
info:
  title: Scanova API - User Management
  description: >-
    User management endpoints for managing shared users, roles, and permissions
    in your Scanova account. These endpoints allow you to invite users, assign
    roles, and manage access levels.
  version: 1.0.0
servers:
  - url: https://management.scanova.io
    description: Scanova Management API Server
security:
  - apiKeyAuth: []
paths:
  /multi-users/access-levels/:
    get:
      tags:
        - User Management
      summary: Get User Roles List
      description: >-
        Get a list of all user roles available in your account. This includes
        default roles (Manager, Admin, Viewer) as well as custom created roles
        with their permissions.
      responses:
        '200':
          description: List of user roles and permissions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccessLevel'
              examples:
                default_roles:
                  summary: Default user roles
                  value:
                    - 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
                      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
                      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
                      is_custom: false
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponse'
      security:
        - apiKeyAuth: []
components:
  schemas:
    AccessLevel:
      type: object
      properties:
        id:
          type: integer
          description: Access level ID
          example: 1
        name:
          type: string
          description: Access level name
          example: Manager
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
          description: List of permissions for this access level
        is_custom:
          type: boolean
          description: Whether this is a custom role or default role
          example: false
    AuthenticationErrorResponse:
      type: object
      properties:
        detail:
          type: string
          example: Authentication credentials were not provided.
    Permission:
      type: object
      properties:
        id:
          type: integer
          description: Permission ID
          example: 22
        code:
          type: string
          description: Permission code
          example: QR_CODE_CAN_ADD
        name:
          type: string
          description: Permission name
          example: Can Add QR Code
        description:
          type: string
          description: Permission description
          example: Can add QR Code
        is_boolean:
          type: boolean
          description: Whether this is a boolean permission
          example: true
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key authentication. Enter your API key directly in the Authorization
        header.

````