Retrieves the details of a group for a specified tenant.

get https://{tenanturl}/v2.0/Groups/{id}

Entitlement required: readUserGroups (Read users and groups), or manageUserGroups (Manage users and groups), or manageAllUserGroups (Synchronize users and groups), or manageUserStandardGroups (Manage users and standard groups), or readGroups (Read all groups but not their members), or readStandardGroups (Read standard groups but not their members), or readGroupMembers (Read all groups and their members), or readStandardGroupMembers (Read standard groups and their members), or manageGroups (Manage all groups but not their members), or manageStandardGroups (Manage standard groups but not their members),or manageGroupMembers (Manage all group and their members), or manageStandardGroupMembers (Manage standard groups and their members).
Note: You only need one entitlement, but you can have more than one.

On Success, the returned response contains the members and details of the group.

Limitations for tenants that do not support large groups:
When specifying the allNestedUsers membershipType, if the number of nested users exceeds 10,000 then the LargeGroupResponse (HTTP Status Code 207) is returned. If the total number of nested users cannot be determined, the totalMembers value is set to -1. When specifying a membershipType other than allNestedUsers, if the group has more than 10,000 members, then the LargeGroupResponse (HTTP Status Code 207) is returned. When the LargeGroupResponse is returned, the memberAttributes, memberCount, and memberStartIndex parameters are ignored.

Tenants that support large groups can page through all the members of a group for all membershipType queries. Each call to the endpoint returns at most 2,500 members of the group. If more members of the group exist that were not returned, an additional element called "bookmark" is returned in the response payload. To get the next set of members, the caller makes an additional call to the same endpoint, and passes the bookmark value as a query parameter named "nextPage". For example ?nextPage=XASDGAJDGKAWHGI=. The caller continues to make calls to the endpoint until no bookmark element are returned in the response payload, which indicates that all group members were returned. The memberStartIndex and memberCount are supported within the 2,500 members returned.

To check whether the tenant supports large groups, run the GET /v2.0/SCIM/capabilities API.

Path Params

string

required

The unique identifier of the group whose details are to be retrieved. This identifier is passed in the path of the URL.

Query Params

membershipType

string

Defaults to firstLevelUsersAndGroups

Type of members of the group to retrieve:
"firstLevelUsersAndGroups" (default) returns the users and groups directly contained in the group."allNestedUsers" returns all the users (including nested users) contained in the group."firstLevelUsers" returns the users directly contained in the group."firstLevelGroups" returns the groups directly contained in the group.

memberAttributes

string

The list of attributes that are passed in as comma-separated values for returning the members of the groups when passing the result back to the caller. To improve performance, specify in the list only the attributes that you want returned. If no list is provided, the default action is to return all attributes.

memberCount

string

The count that indicates the number of members from this group that will be returned. A negative value is interpreted as 0. A value of 0 indicates that no member results are to be returned, except for totalMembers.

memberStartIndex

string

A 1-based index that indicates the start index that is used when the members in the group are returned. A value less than 1 is interpreted as 1.

string

The bookmark that indicates the next page of members to be returned.

Responses

Response body

object

schemas

array of strings

required

An array of strings that contain the URIs that indicate the namespaces of the SCIM schemas that define the attributes in the current JSON structure. The schemas "urn:ietf:params:scim:schemas:core:2.0:Group" and "urn:ietf:params:scim:schemas:extension:ibm:2.0:Group" are returned in the response.

schemas*

string

The unique identifier for the resource as defined by the service. This attribute is read-only and will be sent by the service. Any value that is specified for this attribute in the JSON POST or PUT request payload is ignored.

displayName

string

required

A human-readable name for the group.

bookmark

string

An opaque string that is used by the system to get the next 2500 members of this group. The existence of this element in the GET /v2.0/Groups/{id} response payload indicates that more members exist that were not returned in the call. To get the next set of members, the caller makes an additional call to the same endpoint, and passes the bookmark value as a query parameter named "nextPage". For example ?nextPage=XASDGAJDGKAWHGI=. The caller can continue to make calls to the endpoint until no bookmark element are returned in the response payload, which indicates that all group members were returned. A bookmark is generated from a membershipType query. The bookmark feature is available for tenants that have large group support enabled.

urn:ietf:params:scim:schemas:extension:ibm:2.0:Group

object

description

string

The description for the group.

groupType

string

The group type. This value is read-only.

standard reserved

membersPerPage

int32

Members per page. For large group support, this property is the count of members returned in the members array.

totalMembers

int32

required

The total number of members that are in the group.

memberStartIndex

int32

The start index of members that are returned on the page.

owners

array of objects

A list of owners for the group. For large group support, the group ownership is automatically set and enforced when the request has restricted groups that are associated with the access token's user subject identifier.

owners

object

value

string

required

The id of the group owner

$ref

string

The URI of the SCIM resource representing the user. This value is readonly.

displayName

string

The display name of the user. This value is readonly.

meta

object

resourceType

string

The field that indicates the type of resource.

created

string

A DateTime string that indicates when the resource was created.

lastModified

string

A DateTime string that indicates when the resource was last modified.

location

string

The URI of the resource that is being returned.

deactivated

string

A readonly string that indicates why the account is deactivated. Valid values are "api", "timestamp", and "cleanup". The value "api" means that the user was deactivated by using an API. The value "timestamp" means that the user was deactivated by the system because the account expired. The value "cleanup" means that the user was deactivated by the system during account cleanup processing.

api timestamp cleanup

members

array of objects

A list of members that belong to this group. If the group has more than 10,000 members, then this array is empty, unless large group support is enabled for the tenant. With large group support enabled, each call to the GET /v2.0/Groups/{id} endpoint returns at most 2,500 members of the group. If more members of the group exist that were not returned, a bookmark is returned in the response. The bookmark is used to get the next set of group members. See the "bookmark" property for more details.

members

object

string

The unique identifier for the resource as defined by the service. This attribute is read-only and is sent by the service. Any value that is specified for this attribute in the JSON POST or PUT request payload is ignored.

externalId

string

Valid for user type members only. A unique identifier for the resource that is defined by the provisioning client. It identifies a resource between the provisioning client and the service provider. The client can use a filter to locate the resource with the identifier from the provisioning domain.

userName

string

required

Valid for user type members only. The unique identifier for the user that is typically used by the user to directly authenticate to the service provider. It is often displayed to the user as their unique identifier within the system (as opposed to the id or externalId attributes, which are generally opaque and not user-friendly identifiers). Each user must include a non-empty userName value. This identifier must be unique across the service consumer's entire set of users. It must be a stable ID that does not change when the same user is returned in subsequent requests.

title

string

Valid for user type members only. The user's title, such as "Vice President".

name

object

required

displayName

string

The name of the user or group that is displayed to users. Each member returned may include a non-empty displayName value. For a user type member, typically it is the full name of the user that is being described, for example, Babs Jensen or Ms. Barbara J Jensen. However, if that information is unavailable, a username or handle can be used, for example, bjensen. The value is the primary textual label by which this user is normally displayed by the service provider when presenting information to users.

preferredLanguage

string

Valid for user type members only. The language code identifying the preferred language of this identity, for example, en-us or fr-ca.

active

boolean

Valid for user type members only. A Boolean value that indicates the user's administrative status. The definitive meaning of this attribute is determined by the service provider. For example, a value of true indicates that the user is, for example, able to log in, while a value of false indicates that the user's account has been suspended. If not specified, the value defaults to true.

emails

array of objects

required

Valid for user type members only. A list of email addresses that are associated with the user.

emails*

object

value

string

required

The e-mail addresses for the user. The value is canonicalized by the service provider. For example, bjensen@example.com instead of bjensen@EXAMPLE.COM. Must be RFC 2822 compliant. Maximum length is 128 characters.

type

string

required

A label that indicates the attribute function; for example, "work". Only a single email is allowed.

work

addresses

array of objects

required

Valid for user type members only. A list of addresses that are associated with the user.

addresses*

object

locality

string

The city or locality component. Maximum length is 128 characters.

country

string

The country name component. Maximum length is 128 characters.

type

string

A label that indicates the attribute's function; for example, "work" or "home".

work

streetAddress

string

The street address. Maximum length is 128 characters.

postalCode

string

The postal code. Maximum length is 40 characters.

formatted

string

The formatted value of the address. Maximum length is 500 characters.

primary

boolean

Indicates whether this is address is the primary address for correspondence.

region

string

The region. Maximum length is 128 characters.

phoneNumbers

array of objects

Valid for user type members only. A list of phone numbers that are associated with the user.

phoneNumbers

object

value

string

required

A list of phone numbers that are associated with the user. The value is be canonicalized by the service provider according to format in RFC3966, for example, "tel:+1-201-555-0123". Canonical type values are work, home, mobile, fax, and pager. Maximum length is 32 characters.

type

string

required

A label that indicates the attribute's function; for example, "work" or "home".

work home mobile pager fax

type

string

required

The type of group member.

user group

urn:ietf:params:scim:schemas:extension:ibm:2.0:User

object

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

object

value

string

required

A sub-attr required by the SCIM specification that contains the "id" of the SCIM resource.

$ref

string

required

A sub-attr required by the SCIM specification the contains the URI of the SCIM resource.

externalId

string

Identifier of the Group resource as defined by the provisioning client.

Language

URL


xxxxxxxxxx
1
curl --request GET \
2
     --url 'https://tenant_url/v2.0/Groups/id?membershipType=firstLevelUsersAndGroups' \
3
     --header 'accept: application/scim+json'

Choose an example:

application/scim+json

200The operation was successful.

207The group has more than 10000 members.

400The request was incorrect.

403Forbidden.

404The group that was requested was not found.

500An internal server error occurred.

529The request timed out.