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' \
     | jq .

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

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"
  }
]