Get users and groups assigned a role
/apiplatform/administration/v1/roles/{roleId}/members
Returns a collection of users and groups that have been assigned the {roleId}
role. By default, the name and ID of each user and group are returned. Additional fields can be returned by sending any of these field names, separated by commas, in the fields
query parameter: for users, createdAt
, createdBy
, department
, email
, phone
, and roles
; for groups, createdAt
, createdBy
, department
, description
, email
, memberCount
, phone
, and roles
. If you send a field that applies to both users and groups (like email
) the field is returned for both.
The response also contains HATEOAS links to related operations.
Users accessing this resource must be assigned the Administrator role.
Request
- application/json
-
roleId: string
A unique ID referencing a specific role.
-
fields(optional): array
Collection Format:
csv
Pass optional fields, separated by commas, in this parameter to return them in the response. See the operation's description for a list of field values. - links(optional): array
Response
- application/json
200 Response
object
-
items(optional):
array items
User and group members.
object
-
count(optional):
integer(int32)
The number of items in this collection.
object
-
links(optional):
array links
Includes 'canonical'.
array
-
Array of:
object RoleMember
A role member can be a user or group.
object
-
createdAt(optional):
string(dateTime)
The date and time the user was added to the role.
-
createdBy(optional):
string
Name of the user who added the user to the role.
-
group(optional):
object GroupPreview
-
user(optional):
object UserPreview
object
-
department(optional):
string
The group's department.
-
email(optional):
string
The group's email address.
-
id:
string
The group's ID.
-
memberCount(optional):
integer(int32)
-
name:
string
The group's name.
-
phone(optional):
string
The group's phone number.
-
roles(optional):
array roles
The group's roles.
object
-
department(optional):
string
The user's department.
-
email(optional):
string
The user's email address.
-
id:
string
The user's ID.
-
name:
string
The user's name.
-
phone(optional):
string
The user's phone number.
-
roles(optional):
array roles
The user's roles.
object
-
id(optional):
string
The role's ID.
-
name(optional):
string
The role's name.
object
-
href(optional):
string
Link href.
-
method(optional):
string
HTTP Operation GET, POST, PUT
-
rel(optional):
string
Link relation.
400 Response
object
-
detail(optional):
string
Detailed error message
-
errorCode(optional):
string
Application specific error code
-
errorDetails(optional):
array errorDetails
additional errors
-
errorPath(optional):
string
-
instance(optional):
string
URI to the link that provides more detail about the error
-
status(optional):
string
HTTP status code
-
title:
string
Summary error message
-
type:
string
Error type
403 Response
object
-
detail(optional):
string
Detailed error message
-
errorCode(optional):
string
Application specific error code
-
errorDetails(optional):
array errorDetails
additional errors
-
errorPath(optional):
string
-
instance(optional):
string
URI to the link that provides more detail about the error
-
status(optional):
string
HTTP status code
-
title:
string
Summary error message
-
type:
string
Error type
500 Response
object
-
detail(optional):
string
Detailed error message
-
errorCode(optional):
string
Application specific error code
-
errorDetails(optional):
array errorDetails
additional errors
-
errorPath(optional):
string
-
instance(optional):
string
URI to the link that provides more detail about the error
-
status(optional):
string
HTTP status code
-
title:
string
Summary error message
-
type:
string
Error type
Examples
The following example shows how to retrieve the users and groups that have been assigned a specific role in Oracle API Platform Cloud Service by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.
curl -i -X GET -u apicsadmin:password https://example.com/apiplatform/administration/v1/roles/APIManager/members
You can pass the following optional field values in the fields
query parameter, separated by commas, to include them in the response:
-
createdAt
: the date and time the user or group was added to the role. -
createdBy
: name of the user who added the user or group to the role. -
department
: thedepartment of the user or group -
email
: the email address of the user or group. -
phone
: the phone number of the user or group. -
roles
: an array of all roles the user or group belongs to. -
description
: a description of the group. -
memberCount
: the number of users and groups that belong to this group.
The following example shows you how to include some of these fields in the response:
curl -i -X GET -u apicsadmin:password https://example.com/apiplatform/administration/v1/roles/APIManager/members?fields=email
Example of Response Headers
The following shows an example of the response headers.
HTTP/1.1 200 OK Server: Oracle-Traffic-Director/12.2.1.0.0 Date: Mon, 02 Jan 2017 14:00:56 GMT Content-length: 754 Content-type: application/json X-oracle-dms-ecid: zAa9s07vR00000000 X-oracle-dms-rid: 0:1 Via: 1.1 otd_opc Proxy-agent: Oracle-Traffic-Director/12.2.1.0.0
Example of Response Body
The following example shows the contents of the response body for a request without additional properties passed in the fields
query parameter in JSON format, including information about the users and groups assigned the role and HATEOAS links to related operations.
{ "count": 2, "links": [ { "templated": "true", "method": "GET", "rel": "self", "href": "https://example.com:443/apiplatform/administration/v1/roles/APIManager/members" }, { "templated": "true", "method": "GET", "rel": "canonical", "href": "https://example.com:443/apiplatform/administration/v1/roles/APIManager/members" } ], "items": [ { "links": [ { "templated": "true", "method": "DELETE", "rel": "revoke", "href": "https://example.com:443/apiplatform/administration/v1/roles/APIManager/members/users/LCMUser" } ], "user": { "name": "LCMUser", "id": "LCMUser" } }, { "links": [ { "templated": "true", "method": "DELETE", "rel": "revoke", "href": "https://example.com:443/apiplatform/administration/v1/roles/APIManager/members/groups/APIManagers" } ], "group": { "name": "APIManagers", "id": "APIManagers" } } ] }
Example of Response Body
The following example shows the contents of the response body for a request that passes the email
field in the fields
query parameter in JSON format, including information about the users and groups assigned the role and HATEOAS links to related operations.
{ "count": 2, "links": [ { "templated": "true", "method": "GET", "rel": "self", "href": "https://example.com:443/apiplatform/administration/v1/roles/APIManager/members" }, { "templated": "true", "method": "GET", "rel": "canonical", "href": "https://example.com:443/apiplatform/administration/v1/roles/APIManager/members" } ], "items": [ { "links": [ { "templated": "true", "method": "DELETE", "rel": "revoke", "href": "https://example.com:443/apiplatform/administration/v1/roles/APIManager/members/users/LCMUser" } ], "user": { "name": "LCMUser", "id": "LCMUser", "email": "lcmuser@example.com" } }, { "links": [ { "templated": "true", "method": "DELETE", "rel": "revoke", "href": "https://example.com:443/apiplatform/administration/v1/roles/APIManager/members/groups/APIManagers" } ], "group": { "name": "APIManagers", "id": "APIManagers", "email": "apimanagers@example.com" } } ] }