Select the tab
ESET Connect – Table of Contents

GET List roles

Relative path: /v2/role-assignments

List [role]s of [subject]s.

Info:
Not only Users are [subject]s, but anything that can have roles attached. For example, Devices.

Info:
Modeled after List role assignments.

Might be filtered by the specified [subject] or [scope]s.

If the filters are left empty, all the roles available to the caller are returned.

Example:
Request*

---  
scopes:  
- msp_uuid: af631cc9-3e9f-4fd7-8f29-ed8121b4cf8a  

Response*

---  
assignments:  
- subject_reference: 286f5456-a0ac-4e8a-8508-5c2224b47ae6  
roles:  
- role_name: admin  
scopes:  
- msp_uuid: af631cc9-3e9f-4fd7-8f29-ed8121b4cf8a  
- customer_uuid: 30bd93aa-c0ef-4fcf-a73f-ce80610bd161  
- role_name: auditor  
scopes:  
- msp_uuid: 30bd93aa-c0ef-4fcf-a73f-ce80610bd161  
- subject_reference: ae9e45d2-9ee6-43e7-9b68-a650d62eeff1  
roles:  
- role_name: admin  
scopes:  
- msp_uuid: af631cc9-3e9f-4fd7-8f29-ed8121b4cf8a  
- customer_uuid: ff572f63-8965-47da-9d9d-cb994dc9da10  
- role_name: auditor  
scopes:  
- msp_uuid: af631cc9-3e9f-4fd7-8f29-ed8121b4cf8a  
- customer_uuid: 30bd93aa-c0ef-4fcf-a73f-ce80610bd161  

Query parameters

Name

Type

Description

includeNestedScopes

boolean

Scopes can be nested, and some scopes naturally exist within the boundaries of another scope.

If true, besides the requested scopes, nested scopes are also included in the response.

subjectReference

string

Return only roles of the subject

Reference can be the User UUID, EPC instance UUID, or whatever identifies the subject.

If omitted, all the subjects (accessible to the caller) are returned.

Info: sub claim can be used: JSON Web Token Claims

Identical to the principal concept from the Microsoft literature: Security principals

subjectType

string

Type of the subject in reference.

SUBJECT_TYPE_UNSPECIFIED: fallback

SUBJECT_TYPE_USER: Subject represents a [user].

SUBJECT_TYPE_DEVICE: Subject represents a [device].

SUBJECT_TYPE_USER_GROUP: Roles can be assigned to a user group.

Then, the roles are inferred from the groups of the authenticated user. - SUBJECT_TYPE_MANAGED_IDENTITY: The subject has a managed identity.

Managed identities are used by the API clients to access services.

pageSize

integer

Limit for pagination purposes.

If unspecified or 0, the default value is 50. The maximum value is 1000; values above 1000 will be coerced to 1000.

Info: For more information, refer to Paginating Requests in APIs

or Design Patterns: Pagination

pageToken

string

Page token of the current page.

If not given or "", the first page is returned.

Info: For more information, refer to Paginating Requests in APIs

or Design Patterns: Pagination

orderBy

string

Comma-separated list of fields (from the request resource).

Allowed formats are: - snake_case version of the field name as used by protocol buffers. - JSON version of the field name

The syntax is described at Standard Methods: List Ordering



Responses

Display Schema instead of an Example or vice-versa

Code

Description

Example

Schema

200

Successful response.

{
  "assignments": [
    {
      "roles": [
        {
          "roleName": "string",
          "scopes": [
            {
              "assetGroupUuid": "string",
              "customerUuid": "string",
              "deviceUuid": "string",
              "mspUuid": "string",
              "policyUuid": "string",
              "siteUuid": "string",
              "subscriptionUuid": "string",
              "userUuid": "string",
              "tenantUuid": "string"
            }
          ]
        }
      ],
      "subjectReference": "string",
      "subjectType": "SUBJECT_TYPE_UNSPECIFIED"
    }
  ],
  "nextPageToken": "string",
  "totalSize": 0
}
{
  "$ref": "v2ListRolesResponse",
  "assignments": [
    {
      "$ref": "v2SubjectRoles",
      "description": "Assignment of [role]s to a [subject].",
      "roles": [
        {
          "$ref": "v2ScopedRole",
          "description": "Combines the [role] and [scope]s. Roles might have effects limited by the scopes. For example, a user might be an admin of a specific device. Info: On the Internet the concept of the scope (for example, Scope) can be found under different names: Condition from: REST Resource: roleAssignments Context from: Term Definition: Contextual Role",
          "roleName": {
            "type": "string",
            "description": "The role name is the identifier of the Role. For example, 'admin', or 'security.viewer', or '2a2b9908-6ea1-4ae2-8e65-a410df84e7d1' Roles are referenced by their names."
          },
          "scopes": [
            {
              "$ref": "v2Scope",
              "description": "[Scope] for a role assignment. Scope narrows down the application of a role. [Scope]s can be hierarchical, which implies role inheritance. Info: On the Internet the concept of the scope (for example, Scope) can be found under different names: Condition from: REST Resource: roleAssignments Context from: Term Definition: Contextual Role",
              "assetGroupUuid": {
                "type": "string",
                "description": "Scope of the referenced [group] from asset management. type: asset_management.v1.Group"
              },
              "customerUuid": {
                "type": "string",
                "description": "Scope of the referenced [customer]. Info: The [customer] scope is covered by the more abstract [tenant] scope, which will eventually be used instead of the [customer] scope. type: customer_management.v2.Customer"
              },
              "deviceUuid": {
                "type": "string",
                "description": "Scope of the referenced [device]. type: device_management.v1.Device"
              },
              "mspUuid": {
                "type": "string",
                "description": "Scope of the referenced [MSP]. Info: The [MSP] scope is covered by the more abstract [tenant] scope, which will eventually be used instead of the [customer] scope. type: msp_management.v1.Msp"
              },
              "policyUuid": {
                "type": "string",
                "description": "Scope of the referenced [policy]. type: policy_management.v1.Policy"
              },
              "siteUuid": {
                "type": "string",
                "description": "[Site] reference. type: organization_site_management.v1.Site"
              },
              "subscriptionUuid": {
                "type": "string",
                "description": "Scope of the referenced [subscription]. type: subscription_management.v1.Subscription"
              },
              "userUuid": {
                "type": "string",
                "description": "Scope of the referenced [user]. type: user_management.v1.User"
              },
              "tenantUuid": {
                "type": "string",
                "description": "Tenant typically represents an organization unit recognized by ESET. Tenant defines the logical scope of the managed entities. Each managed entity is owned by exactly one tenant, which means its life cycle is inherently dependent on the tenant’s life cycle. type: tenant_management.v1.Tenant"
              }
            }
          ]
        }
      ],
      "subjectReference": {
        "type": "string",
        "description": "Reference of the subject. Info: Identical to the principal concept from the Microsoft literature: Security principals"
      },
      "subjectType": {
        "$ref": "v2SubjectType",
        "type": "string",
        "description": "The type of principal represented by the subject to whom the roles are assigned. SUBJECT_TYPE_UNSPECIFIED: fallback SUBJECT_TYPE_USER: Subject represents a [user]. SUBJECT_TYPE_DEVICE: Subject represents a [device]. SUBJECT_TYPE_USER_GROUP: Roles can be assigned to a user group. Then, the roles are inferred from the groups of the authenticated user. - SUBJECT_TYPE_MANAGED_IDENTITY: The subject has a managed identity. Managed identities are used by the API clients to access services.",
        "default": "SUBJECT_TYPE_UNSPECIFIED",
        "enum": [
          "SUBJECT_TYPE_UNSPECIFIED",
          "SUBJECT_TYPE_USER",
          "SUBJECT_TYPE_DEVICE",
          "SUBJECT_TYPE_USER_GROUP",
          "SUBJECT_TYPE_MANAGED_IDENTITY"
        ]
      }
    }
  ],
  "nextPageToken": {
    "type": "string",
    "description": "Page token of the next page. Empty or '' for the last page. Info: For more information, refer to Paginating Requests in APIs or Design Patterns: Pagination"
  },
  "totalSize": {
    "type": "integer",
    "description": "The total count of items in the list irrespective of pagination. Info: One of the standard fields Page_size might differ for every call (it is an input parameter) so the calculation of how many pages there is in total is caller's responsibility.",
    "format": "int64"
  }
}

202

Response took too long; request cached. Response can be retrieved later using the response-id header.

null
[]

400

One of the errors: 1. Bad or missing authorization. 2. Validation error. Invalid argument provided.

null
[]

401

Token has expired or is invalid.

null
[]

403

Access denied. Check permissions.

null
[]

404

Requested resource not found.

null
[]

429

Rate limit reached. Try again later.

null
[]

500

Internal server failure. Try again later.

null
[]

502

Internal server failure. Try again later.

null
[]

503

Environment under maintenance. Try again later.

null
[]

504

Action took too long; timeout reached

null
[]