Retrieves a list of groups that belong to the specified tenant and match the search criteria.

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

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.

The members attribute is not returned in the response.

Searching, sorting, paging, and filtering are supported.

Query Params

filter

string

The SCIM compliant search filter. For example, displayName eq "admin". The filter should be no longer than 4096 characters in length.

attributes

string

The list of attributes that are passed in as comma-separated values that are used 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.

count

string

Specifies the maximum number of query results per page. A negative value is interpreted as 0. A value of 0 indicates that no resource results are to be returned, except for totalResults.

startIndex

string

A 1-based index that indicates the start index that is used when the number of groups is returned. A value less than 1 is interpreted as 1.

sortBy

string

Sort the results by the specified criteria when the groups are returned.

sortOrder

string

The sorting order when the number of groups is returned.

fullText

string

A string that is searched for in the group records.

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 schema "urn:ietf:params:scim:api:messages:2.0:ListResponse" is returned in the response.

schemas*

Resources

array of objects

A list of groups.

Resources

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

meta

object

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 \
3
     --header 'accept: application/scim+json'

Choose an example:

application/scim+json

200The operation was successful.

400The request was incorrect.

403Forbidden.

500An internal server error occurred.

529The request timed out.