List a role's members

List members within a role.

If a kind query parameter is used, the results are narrowed to only resources of that kind.

If a limit is provided, the results return up to the number specified. Providing an offset skips a number of resources before returning the rest. In addition, providing an offset gives limit a default value of 10 if no other limit is provided. These two parameters can be combined to page through results.

If the parameter count is true, the number of items in the list are returned.

Text search

If the search parameter is provided, the results are narrowed to those pertaining to the search query. Search works across resource IDs and the values of annotations. It weighs results so that those with matching id or a matching value of an annotation called name appear first, then those with another matching annotation value, and finally those with a matching kind.

Types of Roles

Role	Description
User	One unique human.
Host	A single logical machine (in the broad sense, not just physical).
Layer	A collection of hosts that have the same privileges.
Group	A collection of users and groups that have the same privileges.
Policy	A role that owns of a set of related objects.

Entity IDs must be URL-encoded.

URI

GET /roles/{account}/{kind}/{identifier}?members

Any identifier included in the URI must be URL-encoded to be recognized by the Conjur API.

Examples:

Identifier	URL-Encoded
`myapp-01`	`myapp-01`(no change)
`alice@devops`	`alice%40devops`
`prod/aws/db-password`	`prod%2Faws%2Fdb-password`
`research+development`	`research%2Bdevelopment`
`sales&marketing`	`sales%26marketing`

Example with curl

Suppose your organization name is myorg and you want to search for the first two members matching the word “db”:

curl -H "$(conjur authn authenticate -H)" \
     'https://eval.conjur.org/roles/myorg/group/devs?members&search=db&limit=2'

Headers

Field	Description	Example
Authorization	Conjur access token.	Token token=“eyJkYX…Rhb=”

Response

Code	Description
200	The response body contains the requested role members.
401	The request lacks valid authentication credentials.
403	The authenticated user lacks the necessary privilege.
404	The requested role does not exist.

Example URI

Suppose the requested members are for a group named “devs” at an organization called myorg:

GET /roles/myorg/group/devs?members

URI Parameters

Parameter	Type	Mandatory	Description
account	String	Yes	Organization account name. Example: `myorg`
kind	String	Yes	Kind of role requested. Example: `group`
identifier	String	Yes	Identifier of the role. Example: `devs`

Parameter

Type

Mandatory

Description

account

String

Yes

Organization account name.

Example: myorg

kind

String

Yes

Kind of role requested.

Example: group

identifier

String

Yes

Identifier of the role.

Example: devs

Request

Headers

Authorization: Token token="eyJkYX...Rhb="

Response 200

Headers

Content-Type: application/json

Body

[
  {
    "admin_option": true,
    "ownership": true,
    "role": "myorg:group:devs",
    "member": "myorg:user:admin",
    "policy": "myorg:policy:root"
  },
  {
    "admin_option": false,
    "ownership": false,
    "role": "myorg:group:devs",
    "member": "myorg:user:alice",
    "policy": "myorg:policy:root"
  },
  {
    "admin_option": false,
    "ownership": false,
    "role": "myorg:group:devs",
    "member": "myorg:user:bob",
    "policy": "myorg:policy:root"
  }
]