Introduction

Access Groups allow for the assignment of many policies to many members in one place. Both users and service IDs can be added to an Access Group. Each Access Group is bound to a specific IBM Cloud Account (as are users and service IDs).

No longer do policies need to be created on a per user/service ID basis. Instead, a policy can be created for an Access Group, and that common policy is shared for all of the group's members. This makes it much easier for administrators to manage access control. It is an analogous concept to access control groups used to manage users in the Linux operating system.

For more details, see: Setting up access groups.

Error handling

The Access Groups REST APIs return standard HTTP status codes to indicate the success or failure of a request. The format of the response is represented in JSON as follows:

{
    "trace": "9daee671-916a-4678-850b-10b911f0236d",
    "errors": [
        {
            "code": "invalid_access_token",
            "message": "The provided access token provided is invalid."
        }
    ]
    "status_code": 401
}

In the event that an operation cannot be fulfilled, an appropriate 400 or 500 series HTTP response is returned from the server. The operations defined in the Reference section describe example errors that may be returned from a failed request. All responses from the Access Groups REST API will be in JSON format.

Below are potential error codes our API may return.

HTTP Error Code Description Recovery
200 Success The request was successful.
201 Created The resource was successfully created.
204 No Content The request was successful. No response body is provided.
207 Multi-Status See the response body to determine the outcome of each request.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. The token is either missing or expired. Get a new valid token and try again.
403 Forbidden The supplied authentication is not authorized to perform the operation. If this error persists, contact the account owner to check your permissions.
404 Not Found The requested resource could not be found.
409 Conflict The entity is already in the requested state.
429 Too Many Requests Too many requests have been made within a given time window. Wait before calling the API again.
503 Service Unavailable Access Groups or one of its internal dependent services is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Authentication

Authorization to the Access Groups REST API is enforced by using an IAM Access Token. The token is used to determine the roles that the identity has access to when using various IAM API services. Obtaining an IAM Token for an authenticated User or Service ID is captured in the IAM Identity Service documentation.

Use of the Access Groups REST API is done by adding a valid IAM Token to the HTTP Authorization request header.

Adequate permissions are required to use the Access Groups APIs. An IAM Administrator or Editor role on the account is required to create groups. However, once a group is created, an IAM Administrator or Editor role on the group can be assigned via an Access Management Policy. An Administrator or Editor of the group can update and delete the group, as well as the create, update, and delete members or rules on the group.

A user with Viewer permissions will be able to retrieve and list groups, members, and rules.

Additional headers

Some additional headers may be required to make successful requests to the API. Those additional headers are:

Transaction-Id:

An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose.

If there is not a transaction ID that is passed in, then one is generated randomly.

Pagination

Some API requests might return a large number of results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for the following resources use pagination:

  • /v2/groups
  • /v2/groups/{access_group_id}/members

The fields first, previous, next, and last are included in the collection response as needed, depending on the size of the result. For example, previous and next are not included on a page size of 1. The href value for these fields contains a URL reference to the appropriate collection resource.

The default page size is 50 items, and the max size is 100 items. To use a different page size, use the limit query parameter.

The field offset can be used to traverse the pages. The offset field specifies the number of resources to skip over given an ordered collection. If an offset is not specified, then the default behavior is to skip over 0 resources.

A total_count field can also be included in the response, indicating how many results exist.

Sorting

Sorting is available on our previously mentioned paginated APIs. Using a sort query parameter set to the field name you want the results sorted by.

To reverse sort, prepend a - to the field name.

For example, for our GET /v2/groups endpoint, a query parameter of sort=name will sort the returned groups in ascending alphabetical order by name. Meanwhile a query parameter of sort=-name will return the groups in descending alphabetical order by name.

Rate limiting

Rate limits for API requests are enforced on a per-caller basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

The response to each HTTP request includes headers you can use to determine whether you are close to the rate limit:

  • X-RateLimit-Reset: the time the current timer expires (in UNIX epoch time)
  • X-RateLimit-Remaining: the number of requests remaining in the current time window
  • X-RateLimit-Limit: the total number of requests allowed within the time window

An HTTP status code of 429 indicates that the rate limit has been exceeded.

The number of allowed requests, and the length of the time window, may vary by method and endpoint.

When working with the Access Groups endpoints, it may be helpful to be aware of other IAM services. View Access Management to learn about policy creation and service registration. View Identity Service to learn about api key, service id, and token creation.

Methods

Create an Access Group

Create a new Access Group to assign multiple users and service ids to multiple policies. The group will be created in the account specified by the account_id parameter. The group name is a required field, but a description is optional. Because the group's name does not have to be unique, it is possible to create multiple groups with the same name.

POST /groups
Request

Custom Headers

  • An optional transaction id for the request

Query Parameters

  • IBM Cloud account id under which the group is created

The Access Group to create

Response

Status Code

  • Group Created

  • Bad Request

  • Invalid Access Token

  • Access Denied

  • Server Error

Example responses

List Access Groups

This API lists Access Groups within an account. Parameters for pagination and sorting can be used to filter the results. The account_id query parameter determines which account to retrieve groups from. Only the groups you have access to are returned (either because of a policy on a specific group or account level access (admin, editor, or viewer)). There may be more groups in the account that aren't shown if you lack the aforementioned permissions.

GET /groups
Request

Custom Headers

  • An optional transaction id for the request

Query Parameters

  • IBM Cloud account id under which the groups are listed

  • Return groups for member id (IBMid or Service Id)

  • Return up to this limit of results where limit is between 0 and 100

    Default: 50

  • Offset the results using this query parameter

    Default: 0

  • Sort the results by id, name, description, or is_federated flag

    Default: name

  • If show_federated is true, each group listed will return an is_federated value that is set to true if rules exist for the group.

    Default: false

Response

Status Code

  • Success

  • Invalid Access Token

  • Access Denied

  • Server Error

Example responses

Get an Access Group

Retrieve an Access Group by its access_group_id. Only the groups data is returned (group name, description, account_id, ...), not membership or rule information. A revision number is returned in the Etag header, which is needed when updating the Access Group.

GET /groups/{access_group_id}
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The Access Group to get

Response

Status Code

  • Get Successful

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Server Error

Example responses

Update an Access Group

Update the group name or description of an existing Access Group using this API. An If-Match header must be populated with the group's most recent revision number (which can be acquired in the Get an Access Group API).

PATCH /groups/{access_group_id}
Request

Custom Headers

  • The current revision number of the group being updated. This can be found in the Get Access Group response Etag header.

  • An optional transaction id for the request

Path Parameters

  • The Access group to update

The Access group to update

Response

Status Code

  • Group Updated

  • Bad Request

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Precondition Failed

  • Server Error

Example responses

Delete an Access Group

This API is used for deleting an Access Group. If the Access Group has no members or rules associated with it, the group and its policies will be deleted. However, if rules or members do exist, set the force parameter to true to delete the group as well as its associated members, rules, and policies.

DELETE /groups/{access_group_id}
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The Access group to delete

Query Parameters

  • If force is true, delete the group as well as its associated members and rules

    Default: false

Response

Status Code

  • Delete Successful

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Group Not Empty

  • Server Error

Example responses

Add members to an Access Group

Use this API to add users (IBMid-...) or service IDs (iam-ServiceId-...) to an Access Group. Any member added gains access to resources defined in the group's policies. To revoke a given user's access, simply remove them from the group. There is no limit to the number of members one group can have, but each iam_id can only be added to 50 groups.

PUT /groups/{access_group_id}/members
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The Access Group to add the members to

List of members to add to the group

Response

Status Code

  • There is a multiple status response. Please check the response body.

  • Bad Input (Including duplicate members in request)

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Server Error

Example responses

List Access Group members

List all members of a given group using this API. Parameters for pagination and sorting can be used to filter the results. The most useful query parameter may be the verbose flag. If verbose=true, user and service ID names will be retrieved for each iam_id. If performance is a concern, leave the verbose parameter off so that name information does not get retrieved.

GET /groups/{access_group_id}/members
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The access_group_id to list members of

Query Parameters

  • Return up to this limit of results where limit is between 0 and 100

    Default: 50

  • Offset the results using this query parameter

    Default: 0

  • Filter the results by member type

  • Return user's email and name for each user id or the name for each service id.

    Default: false

  • If verbose is true, sort the results by id, name, or email

Response

Status Code

  • Success

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Server Error

Example responses

Check membership in an Access Group

This HEAD operation determines if a given iam_id is present in a group. No response body is returned with this request. If the membership exists, a 204 - No Content status code is returned. If the membership or the group does not exist, a 404 - Not Found status code is returned.

HEAD /groups/{access_group_id}/members/{iam_id}
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The access_group_id to check for membership in

  • The iam_id to look for within the group

Response

Status Code

  • Membership exists

  • Invalid Access Token

  • Access Denied

  • Membership not found

  • Server Error

Example responses

Delete member from an Access Group

Remove one member from a group using this API. If the operation is successful, only a 204 - No Content response with no body is returned. However, if any error occurs, the standard error format will be returned.

DELETE /groups/{access_group_id}/members/{iam_id}
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The access_group_id to find the membership in

  • The iam_id to remove from the group

Response

Status Code

  • Membership deleted

  • Invalid Access Token

  • Access Denied

  • Membership not found

  • Service Unavailable

Example responses

Delete member from all Access Groups

This API removes a given member from every group they are a member of within the specified account. By using one operation, you can revoke one member's access to all Access Groups in the account. If a partial failure occurs on deletion, the response will be shown in the body.

DELETE /groups/_allgroups/members/{iam_id}
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The iam_id to remove from all groups

Query Parameters

  • IBM Cloud account id for the group membership deletion

Response

Status Code

  • There is a multiple status response. Please check the response body.

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Service Unavailable

Example responses

Create rule for an Access Group

Rules can be used to dynamically add users to an Access Group. If a user's SAML assertions match the rule's conditions during login, the user will be dynamically added to the group. The duration of the user's access to the group is determined by the expiration field. After access expires, the user will need to log in again to regain access. Note that the condition's value field must be a stringified JSON value. Consult this documentation for further explanation of dynamic rules.

POST /groups/{access_group_id}/rules
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The id of the group that the rule will be added to

Response

Status Code

  • Rule Created

  • Bad Request

  • Invalid Access Token

  • Access Denied

  • Group not found

  • Server Error

Example responses

List Access Group rules

This API lists all rules in a given Access Group. Because only a few rules are created on each group, there is no pagination or sorting support on this API.

GET /groups/{access_group_id}/rules
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The group id that the rules are bound to

Response

Status Code

  • List all rules in the given access group

  • Invalid Access Token

  • Access Denied

  • Group not found

  • Server Error

Example responses

Get an Access Group rule

Retrieve a rule from an Access Group. A revision number is returned in the Etag header, which is needed when updating the rule.

GET /groups/{access_group_id}/rules/{rule_id}
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The group id that the rule is bound to

  • The rule to get

Response

Status Code

  • Get Rule Successful

  • Bad Request

  • Invalid Access Token

  • Access Denied

  • Rule not found

  • Server Error

Example responses

Update an Access Group rule

Update the body of an existing rule using this API. An If-Match header must be populated with the rule's most recent revision number (which can be acquired in the Get an Access Group rule API).

PUT /groups/{access_group_id}/rules/{rule_id}
Request

Custom Headers

  • The current revision number of the rule being updated. This can be found in the Get Rule response Etag header.

  • An optional transaction id for the request

Path Parameters

  • The group id that the rule is bound to

  • The rule to update

Response

Status Code

  • Rule Updated

  • Bad Request

  • Invalid Access Token

  • Access Denied

  • Rule not found

  • Precondition Failed

  • Server Error

Example responses

Delete an Access Group rule

Remove one rule from a group using this API. If the operation is successful, only a 204 - No Content response with no body is returned. However, if any error occurs, the standard error format will be returned.

DELETE /groups/{access_group_id}/rules/{rule_id}
Request

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The group id that the rule is bound to

  • The rule to delete

Response

Status Code

  • Delete Successful

  • Invalid Access Token

  • Access Denied

  • Rule not found

  • Server Error

Example responses