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

# Get Roles

> Retrieve data for all roles registered on the platform

## Overview

The Roles endpoint provides access to role definitions, permissions, and assigned users within the ThreatAware platform.

## Parameters

<ParamField query="offset" type="number" default="0">
  Set the start position of the data returned by the API
</ParamField>

<ParamField query="limit" type="number" default="0">
  Limit each request by the provided number. Leave blank or as 0 to return all data available
</ParamField>

## Authentication

<ParamField header="X-ThreatAware-ApiKey" type="string" required>
  Your ThreatAware API key
</ParamField>

<ParamField header="Accept" type="string" default="application/json">
  Response format
</ParamField>

## Response

<ResponseField name="offset" type="number">
  The starting position of this result set
</ResponseField>

<ResponseField name="limit" type="number">
  The number of results returned
</ResponseField>

<ResponseField name="total" type="number">
  Total number of roles
</ResponseField>

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="statusCode" type="number">
  HTTP status code
</ResponseField>

<ResponseField name="message" type="string">
  Status message
</ResponseField>

<ResponseField name="data" type="array">
  <Expandable title="Role Object">
    <ResponseField name="id" type="string">
      Role identifier (e.g., `superAdmin`, `analyst`, `viewer`)
    </ResponseField>

    <ResponseField name="name" type="string">
      Human-readable role name
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of the role and its purpose
    </ResponseField>

    <ResponseField name="default" type="boolean">
      Whether this is a default (built-in) role
    </ResponseField>

    <ResponseField name="permissions" type="object">
      <Expandable title="Permission Object">
        Granular permissions for various platform features:

        * `deviceVisibility`: Access level to devices (`All`, `Team`, `None`)
        * `userVisibility`: Access level to users
        * `integrations`: Integration management permission
        * `vitals`: Vitals configuration permission
        * `workflowAutomation`: Action/automation permission
        * `users`: User management permission
        * `roles`: Role management permission
        * `teams`: Team management permission
        * And many more...
      </Expandable>
    </ResponseField>

    <ResponseField name="users" type="array">
      Users assigned to this role

      <Expandable title="User Object">
        <ResponseField name="username" type="string">
          User email/username
        </ResponseField>

        <ResponseField name="name" type="string">
          First name
        </ResponseField>

        <ResponseField name="surname" type="string">
          Last name
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://your-cloud-id.threataware.com/public-api/v1/settings/usermanagement/roles' \
    --header 'Accept: application/json' \
    --header 'X-ThreatAware-ApiKey: your-api-key-here'
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "your-api-key-here"
  CLOUD_ID = "sandbox"
  BASE_URL = f"https://{CLOUD_ID}.threataware.com/public-api/v1"

  headers = {
      "Accept": "application/json",
      "X-ThreatAware-ApiKey": API_KEY
  }

  response = requests.get(
      f"{BASE_URL}/settings/usermanagement/roles",
      headers=headers
  )

  roles = response.json()
  print(f"Retrieved {len(roles['data'])} roles")

  # Example: Find custom (non-default) roles
  custom_roles = [r for r in roles['data'] if not r.get('default', False)]
  print(f"Custom roles: {len(custom_roles)}")
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const API_KEY = 'your-api-key-here';
  const CLOUD_ID = 'sandbox';
  const BASE_URL = `https://${CLOUD_ID}.threataware.com/public-api/v1`;

  axios.get(`${BASE_URL}/settings/usermanagement/roles`, {
    headers: {
      'Accept': 'application/json',
      'X-ThreatAware-ApiKey': API_KEY
    }
  })
    .then(response => {
      console.log(`Retrieved ${response.data.data.length} roles`);

      // Example: List role names
      response.data.data.forEach(role => {
        console.log(`- ${role.name} (${role.users.length} users)`);
      });
    });
  ```

  ```powershell PowerShell theme={null}
  $ApiKey = "your-api-key-here"
  $CloudId = "sandbox"
  $BaseUrl = "https://$CloudId.threataware.com/public-api/v1"

  $Headers = @{
      "Accept" = "application/json"
      "X-ThreatAware-ApiKey" = $ApiKey
  }

  $Response = Invoke-RestMethod `
      -Uri "$BaseUrl/settings/usermanagement/roles" `
      -Headers $Headers `
      -Method Get

  Write-Host "Retrieved $($Response.data.Count) roles"

  # Example: Show role summary
  $Response.data | Select-Object name, @{Name="Users";Expression={$_.users.Count}} | Format-Table
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK (Truncated for brevity) theme={null}
  {
    "offset": 0,
    "limit": 1,
    "total": 10,
    "data": [
      {
        "id": "superAdmin",
        "name": "Super Admin",
        "description": "Grants the users the highest level of privilege in the platform.",
        "permissions": {
          "deviceVisibility": "All",
          "userVisibility": "All",
          "integrations": "Manage",
          "alertNotes": "Manage",
          "deviceNotes": "Manage",
          "userNotes": "Manage",
          "globalTags": "Manage",
          "apiKeys": "Manage",
          "miscellaneous": "Manage",
          "reports": "Export",
          "scheduledReports": "Manage",
          "previousReports": "Download",
          "browserExtensionAccess": "Login",
          "vitals": "Manage",
          "workflowAutomation": "Manage",
          "vitalsAlerts": "Action",
          "users": "Manage",
          "roles": "Manage",
          "teams": "Manage",
          "ssoSetup": "Manage"
        },
        "default": true,
        "users": [
          {
            "username": "brandon.taylor@company.com",
            "name": "Brandon",
            "surname": "Taylor"
          },
          {
            "username": "gavin.watkins@company.com",
            "name": "Gavin",
            "surname": "Watkins"
          },
          {
            "username": "julian.edwards@company.com",
            "name": "Julian",
            "surname": "Edwards"
          }
        ]
      }
    ],
    "success": true,
    "statusCode": 200,
    "message": "Successfully retrieved roles."
  }
  ```
</ResponseExample>

## Common Roles

<AccordionGroup>
  <Accordion title="Super Admin">
    **Full platform access**

    * All permissions enabled
    * User, role, and team management
    * Integration and API key management
    * SSO configuration
  </Accordion>

  <Accordion title="Analyst">
    **Security operations focus**

    * View all devices and users
    * Manage alerts and actions
    * Export reports
    * Limited administrative access
  </Accordion>

  <Accordion title="Viewer">
    **Read-only access**

    * View devices, users, and alerts
    * Generate reports
    * No modification permissions
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Access Review" icon="clipboard-check">
    Export role assignments for periodic access reviews
  </Card>

  <Card title="Compliance Reporting" icon="file-shield">
    Document role-based access control (RBAC) for audits
  </Card>

  <Card title="Permission Auditing" icon="shield-halved">
    Track which users have administrative permissions
  </Card>

  <Card title="Onboarding Automation" icon="user-plus">
    Automate role assignment based on department or job title
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Users" icon="users" href="/api-reference/settings-users">
    View user accounts and their assigned roles
  </Card>

  <Card title="Get Teams" icon="users" href="/api-reference/settings-teams">
    View team structure and members
  </Card>
</CardGroup>