describeRoles

 

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

true

false

roles

.objects

The "objects" property lists the objects associated with the role that matched the parameters in the request.  array of objects

"objectType"

"permissions"

"recursiveDenials"

"shallowDenials"

roles

objects

.objectType

The "objectType" property specifies the type of object for which privileges are returned.  string enum

"server"

"database"

"table"

"view"

"account"

"role"

"codepackage"

"synonym"

"procedure"

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 "recursiveDenials" property denies a role from having the specified privileges and their descendants. For example, if you deny a role from managing a server, it also denies all its descendant privileges which includes all non-security privileges. 

Note Only privileges with "manage" in their name have descendants. Because of this, "recursiveDenials" is different from "shallowDenials" only for "manage" privileges. 

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