Users Roles
- Last UpdatedAug 23, 2023
- 3 minute read
APIs for getting, updating, and deleting users roles.
List Roles for User
Returns a list of roles for a given user.
Request
GET /api/v1/Tenants/{tenantId}/Users/{userId}/Roles
?query={query}&skip={skip}&count={count}
Parameters
string tenantId
Tenant identifier.string userId
User identifier.
[optional] string query
(Not supported) Search string identifier.[optional] integer skip
Parameter representing the zero-based offset of the first object to retrieve. If unspecified, a default value of 0 is used.[optional] integer count
Parameter representing the maximum number of objects to retrieve. If unspecified, a default value of 100 is used.
Response
| Status Code | Body Type | Description |
|---|---|---|
| 200 | Role[] | List of roles found |
| 400 | ErrorResponse | Missing or invalid inputs. |
| 401 | ErrorResponse | Unauthorized. |
| 403 | ErrorResponse | Forbidden. |
| 404 | ErrorResponse | Tenant or user not found |
| 500 | ErrorResponse | Internal server error. |
Example response body
200 Response (Role[])
[
{
"Id": "string",
"Name": "string",
"Description": "string",
"RoleScope": 0,
"TenantId": "string",
"CommunityId": "string",
"RoleTypeId": "string"
}
]
Authorization
Allowed for these roles:
- Self
- Tenant Member
Get Roles for User Header
Head request to return the total number of user roles for the specified user.
Request
HEAD /api/v1/Tenants/{tenantId}/Users/{userId}/Roles
Parameters
string tenantId
Tenant identifier.string userId
User identifier.
Response
| Status Code | Body Type | Description |
|---|---|---|
| 200 | None | Headers for roles found |
| 401 | None | Unauthorized. |
| 403 | None | Forbidden. |
| 404 | None | Tenant or user not found |
| 500 | None | Internal server error. |
Authorization
Allowed for these roles:
- Self
- Tenant Member
Replace User's Roles
Replaces existing user roles with the set of roles passed in through the request body for the given user. This can be done with existing users.
Request
PUT /api/v1/Tenants/{tenantId}/Users/{userId}/Roles
Parameters
string tenantId
Tenant identifier.string userId
User identifier.
Request Body
Updates roles list
Response
| Status Code | Body Type | Description |
|---|---|---|
| 200 | Role[] | List of updated user roles |
| 400 | ErrorResponse | Missing or invalid inputs. |
| 401 | ErrorResponse | Unauthorized. |
| 403 | ErrorResponse | Forbidden. |
| 404 | ErrorResponse | User or tenant not found |
| 408 | ErrorResponse | Operation timed out. |
| 500 | ErrorResponse | Internal server error. |
Example response body
200 Response (Role[])
[
{
"Id": "string",
"Name": "string",
"Description": "string",
"RoleScope": 0,
"TenantId": "string",
"CommunityId": "string",
"RoleTypeId": "string"
}
]
Authorization
Allowed for these roles:
- Tenant Administrator
Definitions
Role
Object for retrieving a role
Properties
| Property Name | Data Type | Required | Nullable | Description |
|---|---|---|---|---|
| Id | string | false | true | Role identifier. Generated by the server upon creation. |
| Name | string | false | true | Role name. This cannot be empty. |
| Description | string | false | true | Role description |
| RoleScope | RoleScope | false | true | Role scope |
| TenantId | string | false | true | Tenant identifier, if this is a Tenant Role. Otherwise, set to null. |
| CommunityId | string | false | true | Community identifier, if this is a Community Role. Otherwise set to null. |
| RoleTypeId | string | false | true | Role type identifier for built-in roles |
{
"Id": "string",
"Name": "string",
"Description": "string",
"RoleScope": 0,
"TenantId": "string",
"CommunityId": "string",
"RoleTypeId": "string"
}
RoleScope
The object that represents the scope of a given role
Enumerated Values
| Property | Value |
|---|---|
| None | 0 |
| Tenant | 1 |
| Community | 2 |
| Cluster | 3 |
ErrorResponse
Object returned whenever there is an error
Properties
| Property Name | Data Type | Required | Nullable | Description |
|---|---|---|---|---|
| OperationId | string | true | false | Operation identifier of action that caused the error |
| Error | string | true | false | Error description |
| Reason | string | true | false | Reason for the error |
| Resolution | string | true | false | Resolution to resolve the error |
| DynamicProperties | object | false | true | Additional properties |
{
"OperationId": "string",
"Error": "string",
"Reason": "string",
"Resolution": "string",
"DynamicProperties": {
"property1": null,
"property2": null
},
"property1": null,
"property2": null
}