The "describeRoles" action describes specified roles that the account is authorized to see. All information about a role is returned along with all privileges assigned to accounts, procedures, and actions.
Important In order to view a role's privileges, both
"describeTheSecurityOfAnyServer"and"describe…Role"are required.
Request examples
Minimal
{
"action": "describeRoles",
"params":
{
"roleNames": [
"role1",
"admin"
]
}
}
Response examples
With security privileges
{
"authToken": replaceWithAuthTokenFromCreateSession,
"result": {
"roles": [
{
"roleName": "role2",
"roleDescription": "This is the description of role2. You can put anything here.",
"objects": []
},
{
"roleName": "admin",
"roleDescription": "",
"builtinAccountRole": true,
"objects": [
{
"objectType": "server",
"permissions": [
"manageTheSecurityOfAnyServer",
"manageAnyServer"
],
"shallowDenials": [],
"recursiveDenials": []
}
]
}
]
},
"requestId": "",
"errorCode": 0,
"errorMessage": ""
}Minimal
{
"authToken": replaceWithAuthTokenFromCreateSession,
"result": {
"roles": [
{
"roleName": "role2",
"roleDescription": "This is the description of role2. You can put anything here.",
"objects": []
},
{
"roleName": "admin",
"roleDescription": "",
"builtinAccountRole": true,
"objects": []
}
]
},
"requestId": "",
"errorCode": 0,
"errorMessage": ""
}
Properties
Request properties ("params")
| Property | Description | Default | Type | Limits (inclusive) |
|---|---|---|---|---|
roleNames |
The "roleNames" property determines which roles will be included in the response. |
Required - No default value | array of strings | One or more "roleName" strings between 1 and 30 bytes |
Response properties ("result")
| Property | Description | Type | Limits (inclusive) |
|---|---|---|---|
roles |
The "roles" property lists all the roles that match the filters set in the request. |
array of objects | 0 or more objects containing a "roleName". |
|
roles .builtinAccountRole |
The "builtinAccountRole" property indicates whether or not the specified role is a role that is built into the account. |
Boolean |
|
|
roles .objects |
The "objects" property lists the objects associated with the role that matched the parameters in the request. |
array of objects |
|
|
roles objects .objectType |
The "objectType" property specifies the type of object for which privileges are returned. |
string enum |
|
|
roles objects .permissions |
The "permissions" property lists the privileges associated with the specified role. |
array of strings | 0 or more privilege strings |
|
roles objects .recursiveDenials |
The
|
array of objects | 0 or more privilege objects |
|
roles objects .shallowDenials |
The "shallowDenials" property denies a role from having the specified privileges but does not deny the descendants of those privileges. For example, you could deny a role from managing a server while permitting the role to manage one of its databases. |
array of objects | 0 or more privilege objects |
|
roles .roleDescription |
The "roleDescription" property defines the new role and provides notes for its use. |
string | 1 to 64 bytes |
|
roles .roleName |
The "roleName" property specifies the name of the role that matches the parameters in the request. |
string | 1 to 30 bytes |