> ## 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.1.0
info:
  title: Scanova Management API (v2)
  description: >-
    The complete Scanova Management API — every endpoint available at
    management.scanova.io (QR codes, folders, tags, leads, forms, analytics,
    plans, shared users & roles), plus the token-creation and usage-stats
    endpoints used to authenticate against it. Every path and request/response
    shape below was verified live against a real API key and the actual running
    backend (Phase 7, 2026-08-16) — not guessed from reading urls.py alone.
  version: 2.0.0
servers:
  - url: https://management.scanova.io
    description: Management API — QR/folder/tag/lead/form/analytics/plans endpoints
security:
  - apiKeyAuth: []
paths:
  /multi-users/access-levels/:
    get:
      summary: List roles (access levels)
      description: >-
        Returns every role assignable to a shared user, including the account's
        default system roles and any custom roles it has created.
      operationId: listManagedAccessLevels
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum:
              - system
              - custom
        - name: search
          in: query
          schema:
            type: string
        - name: ordering
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of roles, each with its permission set.
          content:
            application/json:
              example:
                count: 6
                next: null
                previous: null
                results:
                  - id: 3
                    name: Viewer
                    slug: viewer
                    permissions:
                      - id: 23
                        code: QR_CODE_CAN_VIEW
                        name: Can view QR Code
                        description: Allows viewing QR code details.
                        is_boolean: true
                    is_custom: false
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Send your Management API key as the raw value of the Authorization
        header — no "Bearer " or "Token " prefix, and no other characters.
        Example: `Authorization: 401f7ac837da42b97f613d789819ff93537bee6a`. A
        header containing more than one space-separated part is rejected
        outright. Requests also require the request's Host header to be the
        management API host (e.g. management.scanova.io) — the same key sent to
        the regular API host will not authenticate.

````