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.
|
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.
|
pageToken |
string |
Page token of the current page. If not given or "", the first page is returned.
|
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 |
[] |