IAM Access Groups | IBM Cloud API Docs

Introduction

Last updated: 2022-10-27

Access groups allow for the assignment of many policies to many members in one place. Users, service IDs and trusted profiles can be added to an access group. Each access group is bound to a specific IBM Cloud® account (as are users, service IDs and trusted profiles).

No longer do policies need to be created on a per user, service ID or trusted profile 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 that are used to manage users in the Linux® operating system. For more information, see Setting up access groups.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/platform-services-go-sdk/iamaccessgroupsv2"
)

Go get

go get -u github.com/IBM/platform-services-go-sdk/iamaccessgroupsv2

View on GitHub

https://github.com/IBM/platform-services-go-sdk

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>iam-access-groups</artifactId>
	<version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:iam-access-groups:{version}'

Replace {version} in these examples with the release version.

View on GitHub

https://github.com/IBM/platform-services-java-sdk

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

pip install --upgrade "ibm-platform-services"

View on GitHub

https://github.com/IBM/platform-services-python-sdk

Endpoint URLs

The IAM Access Groups API uses the following public global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://iam.cloud.ibm.com

If you enabled service endpoints in your account, you can send API requests over the IBM Cloud private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.

Private endpoint URL for VPC infrastructure: https://private.iam.cloud.ibm.com/v2
Private endpoint URLs for classic infrastructure:
- Dallas: https://private.us-south.iam.cloud.ibm.com/v2
- Washington DC: https://private.us-east.iam.cloud.ibm.com/v2

Example API request

curl -X {request_method} "https://private.iam.cloud.ibm.com/v2/{method_endpoint}"

Replace {request_method} and {method_endpoint} in the example with the values for your particular API call.

Authentication

Authorization to the Access Groups REST API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer <TOKEN>'.

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

An IAM Administrator or Editor role on the Access Groups account management service is required to create groups. However, when a group is created, an IAM Administrator or Editor role on the group can be assigned by using an access policy that targets the specific group. An Administrator or Editor of the group can update and delete the group, and add, update, and delete members or rules for the group. A user with Viewer role on the Access Groups service can retrieve and list groups, members, and rules.

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey=<API_KEY>'

Replace <API_KEY> with your IAM API key.

Setting client options through external configuration

Example environment variables, where <API_KEY> is your IAM API key

export IAM_ACCESS_GROUPS_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/iamaccessgroupsv2"
}
...
iamAccessGroupsServiceOptions := &iamaccessgroupsv2.IamAccessGroupsV2Options{}

iamAccessGroupsService, err := iamaccessgroupsv2.NewIamAccessGroupsV2UsingExternalConfig(iamAccessGroupsServiceOptions)

Setting client options through external configuration

Example environment variables, where <API_KEY> is your IAM API key

export IAM_ACCESS_GROUPS_APIKEY=<API_KEY>

Example of constructing the service client

import com.ibm.cloud.platform_services.iam_access_groups.v2.IamAccessGroups;
...
IamAccessGroups iamAccessGroupsService = IamAccessGroups.newInstance();

Setting client options through external configuration

Example environment variables, where <API_KEY> is your IAM API key

export IAM_ACCESS_GROUPS_APIKEY=<API_KEY>

Example of constructing the service client

const IamAccessGroupsV2 = require('@ibm-cloud/platform-services/iam-access-groups/v2');
...
const iamAccessGroupsService = IamAccessGroupsV2.newInstance({});

Setting client options through external configuration

Example environment variables, where <API_KEY> is your IAM API key

export IAM_ACCESS_GROUPS_APIKEY=<API_KEY>

Example of constructing the service client

from ibm_platform_services import IamAccessGroupsV2
...
iam_access_groups_service = IamAccessGroupsV2.new_instance()

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. When an API method is called, an event is generated that you can then track and audit from within Activity Tracker. For methods that generate these events, the specific event type is listed with each individual method.

For more information about how to track Identity and Access Management activity, see Auditing events for IAM.

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
}

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

The following table described the potential error codes the API might 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 can't not be found.
`405`	Method Not Allowed	Access Groups does not support the operation on the target resource. Some operations are not supported on particular groups such as the Public Access group.
`409`	Conflict	The entity is already in the requested state.
`429`	Too Many Requests	Too many requests have been made within a time window. Wait before calling the API again.
`500`	Internal Server Error	Access Groups had an internal server error and could not process the request.
`503`	Service Temporarily Unavailable	Access Groups or one of its internal dependent services is currently unavailable. Your request can't be processed. Wait a few minutes and try again.

Additional headers

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

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 many 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 the previously mentioned paginated APIs. Using a sort query parameter set to the field name you want the results sorted by.

To reverse sort, add a - prefix to the field name.

For example, for the GET /v2/groups endpoint, a query parameter of sort=name sorts the returned groups in ascending alphabetical order by name. Meanwhile a query parameter of sort=-name returns 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 that remain 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, might vary by method and endpoint.

When working with the Access Groups endpoints, it might be helpful to be aware of other IAM services. See Access Management to learn about policy creation and service registration. See Identity Services to learn about API keys, service IDs, and token creation.

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 /v2/groups

(iamAccessGroups *IamAccessGroupsV2) CreateAccessGroup(createAccessGroupOptions *CreateAccessGroupOptions) (result *Group, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) CreateAccessGroupWithContext(ctx context.Context, createAccessGroupOptions *CreateAccessGroupOptions) (result *Group, response *core.DetailedResponse, err error)

ServiceCall<Group> createAccessGroup(CreateAccessGroupOptions createAccessGroupOptions)

createAccessGroup(params)

create_access_group(self,
        account_id: str,
        name: str,
        *,
        description: str = None,
        transaction_id: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.groups.create

Auditing

Calling this method generates the following auditing event.

iam-groups.group.create

Request

Instantiate the CreateAccessGroupOptions struct and set the fields to provide parameter values for the CreateAccessGroup method.

Use the CreateAccessGroupOptions.Builder to create a CreateAccessGroupOptions object that contains the parameter values for the createAccessGroup method.

Custom Headers

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

Query Parameters

account_id
Required*
string
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.

Request Body

Required*

CreateGroupRequest

The access group to create.

Examples:

View

parameter

WithContext method only

CreateAccessGroupOptions

The CreateAccessGroup options.

CreateAccessGroupOptions

The createAccessGroup options.

parameters

accountId
Required*
string
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
name
Required*
string
Assign the specified name to the access group. This field is case-insensitive and has a limit of 100 characters. The group name has to be unique within an account.

Examples:
value
_source
_lines
_html
description
string
Assign an optional description for the access group. This field has a limit of 250 characters.

Examples:
value
_source
_lines
_html
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

account_id
Required*
str
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
name
Required*
str
Assign the specified name to the access group. This field is case-insensitive and has a limit of 100 characters. The group name has to be unique within an account.

Examples:
value
_source
_lines
_html
description
str
Assign an optional description for the access group. This field has a limit of 250 characters.

Examples:
value
_source
_lines
_html
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "name": "Managers", "description": "Group for managers" }'   "{base_url}/v2/groups?account_id={account_id}"

Example request

createAccessGroupOptions := iamAccessGroupsService.NewCreateAccessGroupOptions(
  testAccountID,
  "Managers",
)
createAccessGroupOptions.SetDescription("Group for managers")

group, response, err := iamAccessGroupsService.CreateAccessGroup(createAccessGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(group, "", "  ")
fmt.Println(string(b))

Example request

CreateAccessGroupOptions createAccessGroupOptions = new CreateAccessGroupOptions.Builder()
  .accountId(testAccountId)
  .name("Managers")
  .description("Group for managers")
  .build();

Response<Group> response = iamAccessGroupsService.createAccessGroup(createAccessGroupOptions).execute();
Group group = response.getResult();

System.out.println(group);

Example request

const params = {
  accountId: testAccountId,
  name: 'Managers',
  description: 'Group for managers'
};

try {
  const res = await iamAccessGroupsService.createAccessGroup(params);
  testGroupId = res.result.id;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

group = iam_access_groups_service.create_access_group(
  account_id=test_account_id,
  name='Managers',
  description='Group for managers'
).get_result()

print(json.dumps(group, indent=2))

Response

Response Body

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Status Code

201
Group Created.
400
Bad Request
401
Invalid Access Token.
403
Access Denied.
409
Group Name Conflicted.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 201

{
  "id": "ACCESS_GROUP_ID",
  "name": "Awesome Developers",
  "description": "Group for awesome developers",
  "account_id": "ACCOUNT_ID",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "CREATOR_ID",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "CREATOR_ID"
}

Success example

{
  "id": "ACCESS_GROUP_ID",
  "name": "Awesome Developers",
  "description": "Group for awesome developers",
  "account_id": "ACCOUNT_ID",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "CREATOR_ID",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "CREATOR_ID"
}

Status 400

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_payload",
      "message": "Payload contains invalid/missing data."
    }
  ],
  "status_code": 400
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_payload",
      "message": "Payload contains invalid/missing data."
    }
  ],
  "status_code": 400
}

Status 401

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Status 403

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Status 409

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_conflict_error",
      "message": "An access group with the name <name> already exists. Enter a different name."
    }
  ],
  "status_code": 409
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_conflict_error",
      "message": "An access group with the name <name> already exists. Enter a different name."
    }
  ],
  "status_code": 409
}

Status 500

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Status 503

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

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 /v2/groups

(iamAccessGroups *IamAccessGroupsV2) ListAccessGroups(listAccessGroupsOptions *ListAccessGroupsOptions) (result *GroupsList, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) ListAccessGroupsWithContext(ctx context.Context, listAccessGroupsOptions *ListAccessGroupsOptions) (result *GroupsList, response *core.DetailedResponse, err error)

ServiceCall<GroupsList> listAccessGroups(ListAccessGroupsOptions listAccessGroupsOptions)

listAccessGroups(params)

list_access_groups(self,
        account_id: str,
        *,
        transaction_id: str = None,
        iam_id: str = None,
        membership_type: str = None,
        limit: int = None,
        offset: int = None,
        sort: str = None,
        show_federated: bool = None,
        hide_public_access: bool = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.groups.list

Auditing

Calling this method generates the following auditing event.

iam-groups.groups.list

Request

Instantiate the ListAccessGroupsOptions struct and set the fields to provide parameter values for the ListAccessGroups method.

Use the ListAccessGroupsOptions.Builder to create a ListAccessGroupsOptions object that contains the parameter values for the listAccessGroups method.

Custom Headers

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

Query Parameters

account_id
Required*
string
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
iam_id
string
Return groups for member ID (IBMid, service ID or trusted profile ID).
search
string
Use search to filter access groups list by id, name or description.
- search=id:<ACCESS_GROUP_ID> - To list access groups by id
- search=name:<ACCESS_GROUP_NAME> - To list access groups by name
- search=description:<ACCESS_GROUP_DESC> - To list access groups by description
membership_type
string
Membership type need to be specified along with iam_id and must be either static, dynamic or all. If membership type is static, members explicitly added to the group will be shown. If membership type is dynamic, members accessing the access group at the moment via dynamic rules will be shown. If membership type is all, both static and dynamic members will be shown.

Default: static
limit
integer
Return up to this limit of results where limit is between 0 and 100.

Possible values: value ≤ 100
Default: 50
offset
integer
The offset of the first result item to be returned.

Default: 0
sort
string
Sort the results by id, name, description, or is_federated flag.

Default: name
show_federated
boolean
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
hide_public_access
boolean
If hide_public_access is true, do not include the Public Access Group in the results.

Default: false

parameter

WithContext method only

ListAccessGroupsOptions

The ListAccessGroups options.

ListAccessGroupsOptions

The listAccessGroups options.

parameters

accountId
Required*
string
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.
iamId
string
Return groups for member ID (IBMid, service ID or trusted profile ID).
membershipType
string
Membership type need to be specified along with iam_id and must be either static, dynamic or all. If membership type is static, members explicitly added to the group will be shown. If membership type is dynamic, members accessing the access group at the moment via dynamic rules will be shown. If membership type is all, both static and dynamic members will be shown.

Default: static
limit
number
Return up to this limit of results where limit is between 0 and 100.

Possible values: value ≤ 100
offset
number
The offset of the first result item to be returned.
sort
string
Sort the results by id, name, description, or is_federated flag.

Default: name
showFederated
boolean
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
hidePublicAccess
boolean
If hide_public_access is true, do not include the Public Access Group in the results.

Default: false

parameters

account_id
Required*
str
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.
iam_id
str
Return groups for member ID (IBMid, service ID or trusted profile ID).
membership_type
str
Membership type need to be specified along with iam_id and must be either static, dynamic or all. If membership type is static, members explicitly added to the group will be shown. If membership type is dynamic, members accessing the access group at the moment via dynamic rules will be shown. If membership type is all, both static and dynamic members will be shown.

Default: static
limit
int
Return up to this limit of results where limit is between 0 and 100.

Possible values: value ≤ 100
offset
int
The offset of the first result item to be returned.
sort
str
Sort the results by id, name, description, or is_federated flag.

Default: name
show_federated
bool
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
hide_public_access
bool
If hide_public_access is true, do not include the Public Access Group in the results.

Default: false

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/groups?account_id={account_id}"

Example request

listAccessGroupsOptions := &iamaccessgroupsv2.ListAccessGroupsOptions{
  AccountID: &testAccountID,
}

pager, err := iamAccessGroupsService.NewAccessGroupsPager(listAccessGroupsOptions)
if err != nil {
  panic(err)
}

var allResults []iamaccessgroupsv2.Group
for pager.HasNext() {
  nextPage, err := pager.GetNext()
  if err != nil {
    panic(err)
  }
  allResults = append(allResults, nextPage...)
}
b, _ := json.MarshalIndent(allResults, "", "  ")
fmt.Println(string(b))

Example request

ListAccessGroupsOptions listAccessGroupsOptions = new ListAccessGroupsOptions.Builder()
    .accountId(testAccountId)
  .build();

AccessGroupsPager pager = new AccessGroupsPager(iamAccessGroupsService, listAccessGroupsOptions);
List<Group> allResults = new ArrayList<>();
while (pager.hasNext()) {
  List<Group> nextPage = pager.getNext();
  allResults.addAll(nextPage);
}

System.out.println(GsonSingleton.getGson().toJson(allResults));

Example request

const params = {
  accountId: testAccountId,
};

const allResults = [];
try {
  const pager = new IamAccessGroupsV2.AccessGroupsPager(iamAccessGroupsService, params);
  while (pager.hasNext()) {
    const nextPage = await pager.getNext();
    expect(nextPage).not.toBeNull();
    allResults.push(...nextPage);
  }
  console.log(JSON.stringify(allResults, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

all_results = []
pager = AccessGroupsPager(
  client=iam_access_groups_service,
  account_id=test_account_id,
)
while pager.has_next():
  next_page = pager.get_next()
  assert next_page is not None
  all_results.extend(next_page)

print(json.dumps(all_results, indent=2))

Response

Response Body

GroupsList

The list of access groups returned as part of a response.

GroupsList

The list of access groups returned as part of a response.

GroupsList

The list of access groups returned as part of a response.

GroupsList

The list of access groups returned as part of a response.

GroupsList

The list of access groups returned as part of a response.

Status Code

200
Success.
401
Invalid Access Token.
403
Access Denied.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 200

{
  "limit": 5,
  "offset": 0,
  "total_count": 20,
  "first": {
    "href": "{endpoint_url}/v2/groups?limit=5&account_id=ACCOUNT_ID&show_federated=true"
  },
  "next": {
    "href": "{endpoint_url}/v2/groups?offset=5&limit=5&account_id=ACCOUNT_ID&show_federated=true"
  },
  "last": {
    "href": "{endpoint_url}/v2/groups?offset=15&limit=5&account_id=ACCOUNT_ID&show_federated=true"
  },
  "groups": [
    {
      "id": "AccessGroupId-PublicAccess",
      "name": "Public Access",
      "description": "This group includes all users and service IDs by default. All group members, including unauthenticated users, are given public access to any resources that are defined in the policies for the group.",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "CREATOR_ID",
      "href": "{endpoint_url}/v2/groups/AccessGroupId-PublicAccess",
      "is_federated": false
    },
    {
      "id": "ACCESS_GROUP_ID",
      "name": "Group 1",
      "description": "Nate's description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID",
      "is_federated": true
    },
    {
      "id": "ACCESS_GROUP_ID",
      "name": "Group 2",
      "description": "Nate's description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID",
      "is_federated": true
    },
    {
      "id": "ACCESS_GROUP_ID",
      "name": "Group 3",
      "description": "Nate's description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID",
      "is_federated": false
    },
    {
      "id": "ACCESS_GROUP_ID",
      "name": "Group 4",
      "description": "Nate's description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID",
      "is_federated": false
    },
    {
      "id": "ACCESS_GROUP_ID",
      "name": "Group 5",
      "description": "Nate's description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID",
      "is_federated": false
    }
  ]
}

Success example

{
  "limit": 5,
  "offset": 0,
  "total_count": 20,
  "first": {
    "href": "{endpoint_url}/v2/groups?limit=5&account_id=ACCOUNT_ID&show_federated=true"
  },
  "next": {
    "href": "{endpoint_url}/v2/groups?offset=5&limit=5&account_id=ACCOUNT_ID&show_federated=true"
  },
  "last": {
    "href": "{endpoint_url}/v2/groups?offset=15&limit=5&account_id=ACCOUNT_ID&show_federated=true"
  },
  "groups": [
    {
      "id": "AccessGroupId-PublicAccess",
      "name": "Public Access",
      "description": "This group includes all users and service IDs by default. All group members, including unauthenticated users, are given public access to any resources that are defined in the policies for the group.",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "CREATOR_ID",
      "href": "{endpoint_url}/v2/groups/AccessGroupId-PublicAccess",
      "is_federated": false
    },
    {
      "id": "ACCESS_GROUP_ID",
      "name": "Group 1",
      "description": "Nate's description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID",
      "is_federated": true
    },
    {
      "id": "ACCESS_GROUP_ID",
      "name": "Group 2",
      "description": "Nate's description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID",
      "is_federated": true
    },
    {
      "id": "ACCESS_GROUP_ID",
      "name": "Group 3",
      "description": "Nate's description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID",
      "is_federated": false
    },
    {
      "id": "ACCESS_GROUP_ID",
      "name": "Group 4",
      "description": "Nate's description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID",
      "is_federated": false
    },
    {
      "id": "ACCESS_GROUP_ID",
      "name": "Group 5",
      "description": "Nate's description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID",
      "is_federated": false
    }
  ]
}

Status 401

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Status 403

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Status 500

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Status 503

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

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 /v2/groups/{access_group_id}

(iamAccessGroups *IamAccessGroupsV2) GetAccessGroup(getAccessGroupOptions *GetAccessGroupOptions) (result *Group, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) GetAccessGroupWithContext(ctx context.Context, getAccessGroupOptions *GetAccessGroupOptions) (result *Group, response *core.DetailedResponse, err error)

ServiceCall<Group> getAccessGroup(GetAccessGroupOptions getAccessGroupOptions)

getAccessGroup(params)

get_access_group(self,
        access_group_id: str,
        *,
        transaction_id: str = None,
        show_federated: bool = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.groups.read

Auditing

Calling this method generates the following auditing event.

iam-groups.group.read

Request

Instantiate the GetAccessGroupOptions struct and set the fields to provide parameter values for the GetAccessGroup method.

Use the GetAccessGroupOptions.Builder to create a GetAccessGroupOptions object that contains the parameter values for the getAccessGroup method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Query Parameters

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

Default: false

parameter

WithContext method only

GetAccessGroupOptions

The GetAccessGroup options.

GetAccessGroupOptions

The getAccessGroup options.

parameters

accessGroupId
Required*
string
The access group identifier.
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.
showFederated
boolean
If show_federated is true, the group will return an is_federated value that is set to true if rules exist for the group.

Default: false

parameters

access_group_id
Required*
str
The access group identifier.
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.
show_federated
bool
If show_federated is true, the group will return an is_federated value that is set to true if rules exist for the group.

Default: false

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/groups/{access_group_id}"

Example request

getAccessGroupOptions := iamAccessGroupsService.NewGetAccessGroupOptions(
  accessGroupIDLink,
)

group, response, err := iamAccessGroupsService.GetAccessGroup(getAccessGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(group, "", "  ")
fmt.Println(string(b))

Example request

GetAccessGroupOptions getAccessGroupOptions = new GetAccessGroupOptions.Builder()
  .accessGroupId(testGroupId)
  .build();

Response<Group> response = iamAccessGroupsService.getAccessGroup(getAccessGroupOptions).execute();
Group group = response.getResult();

System.out.println(group);

Example request

const params = {
  accessGroupId: testGroupId,
};

try {
  const res = await iamAccessGroupsService.getAccessGroup(params);
  testGroupETag = res.headers['etag'];
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

response = iam_access_groups_service.get_access_group(
  access_group_id=test_group_id
)
group = response.get_result()

print(json.dumps(group, indent=2))

Response

Response Body

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Status Code

200
Get Successful.
401
Invalid Access Token.
403
Access Denied.
404
Not Found.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 200

{
  "id": "ACCESS_GROUP_ID",
  "name": "Awesome Developers",
  "description": "Group for awesome developers",
  "account_id": "ACCOUNT_ID",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "CREATOR_ID",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "LAST_MODIFIER_ID",
  "is_federated": true
}

Success example

{
  "id": "ACCESS_GROUP_ID",
  "name": "Awesome Developers",
  "description": "Group for awesome developers",
  "account_id": "ACCOUNT_ID",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "CREATOR_ID",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "LAST_MODIFIER_ID",
  "is_federated": true
}

Status 401

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Status 403

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Status 404

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_found",
      "message": "Failed to find the specified access group: <id>"
    }
  ],
  "status_code": 404
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_found",
      "message": "Failed to find the specified access group: <id>"
    }
  ],
  "status_code": 404
}

Status 500

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Status 503

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

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 /v2/groups/{access_group_id}

(iamAccessGroups *IamAccessGroupsV2) UpdateAccessGroup(updateAccessGroupOptions *UpdateAccessGroupOptions) (result *Group, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) UpdateAccessGroupWithContext(ctx context.Context, updateAccessGroupOptions *UpdateAccessGroupOptions) (result *Group, response *core.DetailedResponse, err error)

ServiceCall<Group> updateAccessGroup(UpdateAccessGroupOptions updateAccessGroupOptions)

updateAccessGroup(params)

update_access_group(self,
        access_group_id: str,
        if_match: str,
        *,
        name: str = None,
        description: str = None,
        transaction_id: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.groups.update

Auditing

Calling this method generates the following auditing event.

iam-groups.group.update

Request

Instantiate the UpdateAccessGroupOptions struct and set the fields to provide parameter values for the UpdateAccessGroup method.

Use the UpdateAccessGroupOptions.Builder to create a UpdateAccessGroupOptions object that contains the parameter values for the updateAccessGroup method.

Custom Headers

If-Match
Required*
string
The current revision number of the group being updated. This can be found in the Create/Get access group response ETag header.
Transaction-Id
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Path Parameters

access_group_id
Required*
string
The access group identifier.

Request Body

Required*

UpdateGroupRequest

The access group to update.

Examples:

View

parameter

WithContext method only

UpdateAccessGroupOptions

The UpdateAccessGroup options.

UpdateAccessGroupOptions

The updateAccessGroup options.

parameters

accessGroupId
Required*
string
The access group identifier.
ifMatch
Required*
string
The current revision number of the group being updated. This can be found in the Create/Get access group response ETag header.
name
string
Assign the specified name to the access group. This field is case-insensitive and has a limit of 100 characters. The group name has to be unique within an account.

Examples:
value
_source
_lines
_html
description
string
Assign an optional description for the access group. This field has a limit of 250 characters.

Examples:
value
_source
_lines
_html
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

access_group_id
Required*
str
The access group identifier.
if_match
Required*
str
The current revision number of the group being updated. This can be found in the Create/Get access group response ETag header.
name
str
Assign the specified name to the access group. This field is case-insensitive and has a limit of 100 characters. The group name has to be unique within an account.

Examples:
value
_source
_lines
_html
description
str
Assign an optional description for the access group. This field has a limit of 250 characters.

Examples:
value
_source
_lines
_html
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "If-Match: {if_match}"   --header "Content-Type: application/json"   --data '{ "name": "Awesome Managers", "description": "Group for awesome managers." }'   "{base_url}/v2/groups/{access_group_id}"

Example request

updateAccessGroupOptions := iamAccessGroupsService.NewUpdateAccessGroupOptions(
  accessGroupIDLink,
  accessGroupETagLink,
)
updateAccessGroupOptions.SetName("Awesome Managers")
updateAccessGroupOptions.SetDescription("Group for awesome managers.")

group, response, err := iamAccessGroupsService.UpdateAccessGroup(updateAccessGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(group, "", "  ")
fmt.Println(string(b))

Example request

UpdateAccessGroupOptions updateAccessGroupOptions = new UpdateAccessGroupOptions.Builder()
  .accessGroupId(testGroupId)
  .ifMatch(testGroupETag)
  .name("Awesome Managers")
  .description("Group for awesome managers")
  .build();

Response<Group> response = iamAccessGroupsService.updateAccessGroup(updateAccessGroupOptions).execute();
Group group = response.getResult();

System.out.println(group);

Example request

const params = {
  accessGroupId: testGroupId,
  ifMatch: testGroupETag,
  name: 'Awesome Managers',
  description: 'Group for awesome managers'
};

try {
  const res = await iamAccessGroupsService.updateAccessGroup(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

group = iam_access_groups_service.update_access_group(
  access_group_id=test_group_id,
  if_match=test_group_etag,
  name='Awesome Managers',
  description='Group for awesome managers'
).get_result()

print(json.dumps(group, indent=2))

Response

Response Body

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Status Code

200
Group Updated.
400
Bad Request.
401
Invalid Access Token.
403
Access Denied.
404
Not Found.
405
Method Not Allowed.
409
Group Name Conflicted.
412
Precondition Failed.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 200

{
  "id": "ACCESS_GROUP_ID",
  "name": "SUPER Awesome Developers",
  "description": "Group for SUPER awesome developers.",
  "account_id": "ACCOUNT_ID",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "CREATOR_ID",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "LAST_MODIFIER_ID"
}

Success example

{
  "id": "ACCESS_GROUP_ID",
  "name": "SUPER Awesome Developers",
  "description": "Group for SUPER awesome developers.",
  "account_id": "ACCOUNT_ID",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "CREATOR_ID",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "LAST_MODIFIER_ID"
}

Status 400

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_payload",
      "message": "Payload contains invalid/missing data."
    }
  ],
  "status_code": 400
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_payload",
      "message": "Payload contains invalid/missing data."
    }
  ],
  "status_code": 400
}

Status 401

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Status 403

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Status 404

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_found",
      "message": "Failed to find the specified access group: <id>"
    }
  ],
  "status_code": 404
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_found",
      "message": "Failed to find the specified access group: <id>"
    }
  ],
  "status_code": 404
}

Status 405

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot update group for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot update group for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}

Status 409

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_conflict_error",
      "message": "An access group with the name <name> already exists. Enter a different name."
    }
  ],
  "status_code": 409
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_conflict_error",
      "message": "An access group with the name <name> already exists. Enter a different name."
    }
  ],
  "status_code": 409
}

Status 412

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "incorrect_etag",
      "message": "If-Match header contains incorrect/invalid etag."
    }
  ],
  "status_code": 412
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "incorrect_etag",
      "message": "If-Match header contains incorrect/invalid etag."
    }
  ],
  "status_code": 412
}

Status 500

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Status 503

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

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 /v2/groups/{access_group_id}

(iamAccessGroups *IamAccessGroupsV2) DeleteAccessGroup(deleteAccessGroupOptions *DeleteAccessGroupOptions) (response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) DeleteAccessGroupWithContext(ctx context.Context, deleteAccessGroupOptions *DeleteAccessGroupOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteAccessGroup(DeleteAccessGroupOptions deleteAccessGroupOptions)

deleteAccessGroup(params)

delete_access_group(self,
        access_group_id: str,
        *,
        transaction_id: str = None,
        force: bool = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.groups.delete

Auditing

Calling this method generates the following auditing event.

iam-groups.group.delete

Request

Instantiate the DeleteAccessGroupOptions struct and set the fields to provide parameter values for the DeleteAccessGroup method.

Use the DeleteAccessGroupOptions.Builder to create a DeleteAccessGroupOptions object that contains the parameter values for the deleteAccessGroup method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Query Parameters

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

Default: false

parameter

WithContext method only

DeleteAccessGroupOptions

The DeleteAccessGroup options.

DeleteAccessGroupOptions

The deleteAccessGroup options.

parameters

accessGroupId
Required*
string
The access group identifier.
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.
force
boolean
If force is true, delete the group as well as its associated members and rules.

Default: false

parameters

access_group_id
Required*
str
The access group identifier.
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.
force
bool
If force is true, delete the group as well as its associated members and rules.

Default: false

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}" "{base_url}/v2/groups/{access_group_id}"

Example request

deleteAccessGroupOptions := iamAccessGroupsService.NewDeleteAccessGroupOptions(
  accessGroupIDLink,
)

response, err := iamAccessGroupsService.DeleteAccessGroup(deleteAccessGroupOptions)
if err != nil {
  panic(err)
}
if response.StatusCode != 204 {
  fmt.Printf("\nUnexpected response status code received from DeleteAccessGroup(): %d\n", response.StatusCode)
}

Example request

DeleteAccessGroupOptions deleteAccessGroupOptions = new DeleteAccessGroupOptions.Builder()
  .accessGroupId(testGroupId)
  .build();

Response<Void> response = iamAccessGroupsService.deleteAccessGroup(deleteAccessGroupOptions).execute();

Example request

const params = {
  accessGroupId: testGroupId,
};

try {
  await iamAccessGroupsService.deleteAccessGroup(params);
} catch (err) {
  console.warn(err);
}

Example request

response = iam_access_groups_service.delete_access_group(
  access_group_id=test_group_id
)

Response

Status Code

204
Delete Successful.
401
Invalid Access Token.
403
Access Denied.
404
Not Found.
405
Method Not Allowed.
409
Group Not Empty.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 401

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Status 403

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Status 404

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_found",
      "message": "Failed to find the specified access group: <id>"
    }
  ],
  "status_code": 404
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_found",
      "message": "Failed to find the specified access group: <id>"
    }
  ],
  "status_code": 404
}

Status 405

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot delete group for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot delete group for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}

Status 409

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_empty",
      "message": "Access group is not empty: <id>"
    }
  ],
  "status_code": 409
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_empty",
      "message": "Access group is not empty: <id>"
    }
  ],
  "status_code": 409
}

Status 500

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Status 503

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Use this API to add users (IBMid-...), service IDs (iam-ServiceId-...) or trusted profiles (iam-Profile-...) to an access group. Any member added gains access to resources defined in the group's policies. To revoke a given members'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. Additionally, this API request payload can add up to 50 members per call.

PUT /v2/groups/{access_group_id}/members

(iamAccessGroups *IamAccessGroupsV2) AddMembersToAccessGroup(addMembersToAccessGroupOptions *AddMembersToAccessGroupOptions) (result *AddGroupMembersResponse, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) AddMembersToAccessGroupWithContext(ctx context.Context, addMembersToAccessGroupOptions *AddMembersToAccessGroupOptions) (result *AddGroupMembersResponse, response *core.DetailedResponse, err error)

ServiceCall<AddGroupMembersResponse> addMembersToAccessGroup(AddMembersToAccessGroupOptions addMembersToAccessGroupOptions)

addMembersToAccessGroup(params)

add_members_to_access_group(self,
        access_group_id: str,
        *,
        members: List['AddGroupMembersRequestMembersItem'] = None,
        transaction_id: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.members.add

Auditing

Calling this method generates the following auditing event.

iam-groups.member.add

Request

Instantiate the AddMembersToAccessGroupOptions struct and set the fields to provide parameter values for the AddMembersToAccessGroup method.

Use the AddMembersToAccessGroupOptions.Builder to create a AddMembersToAccessGroupOptions object that contains the parameter values for the addMembersToAccessGroup method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Request Body

Required*

AddGroupMembersRequest

List of members to add to the group. This field has a limit of 50 members.

Examples:

View

parameter

WithContext method only

AddMembersToAccessGroupOptions

The AddMembersToAccessGroup options.

AddMembersToAccessGroupOptions

The addMembersToAccessGroup options.

parameters

accessGroupId
Required*
string
The access group identifier.
members
An array of member objects to add to an access group.

Examples:
value
_source
_lines
_html
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

access_group_id
Required*
str
The access group identifier.
members
An array of member objects to add to an access group.

Examples:
value
_source
_lines
_html
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "members": [ { "iam_id": "IBMid-user1", "type": "user" }, { "iam_id": "iam-ServiceId-123", "type": "service" }, { "iam_id": "iam-Profile-123", "type": "profile" } ] }'   "{base_url}/v2/groups/{access_group_id}/members"

Example request

groupMembers := []iamaccessgroupsv2.AddGroupMembersRequestMembersItem{
  iamaccessgroupsv2.AddGroupMembersRequestMembersItem{
    IamID: core.StringPtr("IBMid-user1"),
    Type:  core.StringPtr("user"),
  },
  iamaccessgroupsv2.AddGroupMembersRequestMembersItem{
    IamID: core.StringPtr("iam-ServiceId-123"),
    Type:  core.StringPtr("service"),
  },
  iamaccessgroupsv2.AddGroupMembersRequestMembersItem{
    IamID: core.StringPtr(testProfileID),
    Type:  core.StringPtr("profile"),
  },
}

addMembersToAccessGroupOptions := iamAccessGroupsService.NewAddMembersToAccessGroupOptions(
  accessGroupIDLink,
)
addMembersToAccessGroupOptions.SetMembers(groupMembers)

addGroupMembersResponse, response, err := iamAccessGroupsService.AddMembersToAccessGroup(addMembersToAccessGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(addGroupMembersResponse, "", "  ")
fmt.Println(string(b))

Example request

AddGroupMembersRequestMembersItem member1 = new AddGroupMembersRequestMembersItem.Builder()
  .iamId("IBMid-user1")
  .type("user")
  .build();
AddGroupMembersRequestMembersItem member2 = new AddGroupMembersRequestMembersItem.Builder()
  .iamId("iam-ServiceId-123")
  .type("service")
  .build();
  AddGroupMembersRequestMembersItem member3 = new AddGroupMembersRequestMembersItem.Builder()
  .iamId(testProfileId)
  .type("profile")
  .build();
AddMembersToAccessGroupOptions addMembersToAccessGroupOptions = new AddMembersToAccessGroupOptions.Builder()
  .accessGroupId(testGroupId)
  .addMembers(member1)
  .addMembers(member2)
  .addMembers(member3)
  .build();
Response<AddGroupMembersResponse> response = iamAccessGroupsService.addMembersToAccessGroup(addMembersToAccessGroupOptions).execute();
AddGroupMembersResponse addGroupMembersResponse = response.getResult();

System.out.println(addGroupMembersResponse);

Example request

const groupMember1 = {
  iam_id: 'IBMid-user1',
  type: 'user',
};
const groupMember2 = {
  iam_id: 'iam-ServiceId-123',
  type: 'service',
};
var groupMember3 = {
  iam_id: profileId,
  type: 'profile',
}

const params = {
  accessGroupId: testGroupId,
  members: [groupMember1, groupMember2, groupMember3],
};

try {
  const res = await iamAccessGroupsService.addMembersToAccessGroup(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

member1 = AddGroupMembersRequestMembersItem(
  iam_id='IBMid-user1', type='user')
member2 = AddGroupMembersRequestMembersItem(
  iam_id='iam-ServiceId-123', type='service')
member3 = AddGroupMembersRequestMembersItem(
  iam_id=test_profile_id, type='profile')
members = [member1, member2, member3]

add_group_members_response = iam_access_groups_service.add_members_to_access_group(
  access_group_id=test_group_id,
  members=members
).get_result()

print(json.dumps(add_group_members_response, indent=2))

Response

Response Body

AddGroupMembersResponse

The members added to an access group.

AddGroupMembersResponse

The members added to an access group.

AddGroupMembersResponse

The members added to an access group.

AddGroupMembersResponse

The members added to an access group.

AddGroupMembersResponse

The members added to an access group.

Status Code

207
There is a multiple status response. Please check the response body.
400
Bad Input (Including duplicate members in request).
401
Invalid Access Token.
403
Access Denied.
404
Not Found.
405
Method Not Allowed.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 207

{
  "members": [
    {
      "iam_id": "$IBM_ID",
      "type": "user",
      "created_at": "2022-01-28T13:34:36Z",
      "created_by_id": "CREATOR_ID",
      "status_code": 200
    },
    {
      "iam_id": "$SERVICE_ID",
      "status_code": 400,
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "The service id is missing or incorrect"
        }
      ]
    },
    {
      "iam_id": "$PROFILE_ID",
      "type": "profile",
      "created_at": "2022-01-28T13:34:36Z",
      "created_by_id": "CREATOR_ID",
      "status_code": 200
    }
  ]
}

Success example

{
  "members": [
    {
      "iam_id": "$IBM_ID",
      "type": "user",
      "created_at": "2022-01-28T13:34:36Z",
      "created_by_id": "CREATOR_ID",
      "status_code": 200
    },
    {
      "iam_id": "$SERVICE_ID",
      "status_code": 400,
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "The service id is missing or incorrect"
        }
      ]
    },
    {
      "iam_id": "$PROFILE_ID",
      "type": "profile",
      "created_at": "2022-01-28T13:34:36Z",
      "created_by_id": "CREATOR_ID",
      "status_code": 200
    }
  ]
}

Status 400

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_payload",
      "message": "Payload contains invalid/missing data."
    }
  ],
  "status_code": 400
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_payload",
      "message": "Payload contains invalid/missing data."
    }
  ],
  "status_code": 400
}

Status 401

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Status 403

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Status 404

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "membership_not_found",
      "message": "Failed to find the membership"
    }
  ],
  "status_code": 404
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "membership_not_found",
      "message": "Failed to find the membership"
    }
  ],
  "status_code": 404
}

Status 405

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot add members for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot add members for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}

Status 500

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Status 503

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

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, service ID and trusted profile 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 /v2/groups/{access_group_id}/members

(iamAccessGroups *IamAccessGroupsV2) ListAccessGroupMembers(listAccessGroupMembersOptions *ListAccessGroupMembersOptions) (result *GroupMembersList, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) ListAccessGroupMembersWithContext(ctx context.Context, listAccessGroupMembersOptions *ListAccessGroupMembersOptions) (result *GroupMembersList, response *core.DetailedResponse, err error)

ServiceCall<GroupMembersList> listAccessGroupMembers(ListAccessGroupMembersOptions listAccessGroupMembersOptions)

listAccessGroupMembers(params)

list_access_group_members(self,
        access_group_id: str,
        *,
        transaction_id: str = None,
        membership_type: str = None,
        limit: int = None,
        offset: int = None,
        type: str = None,
        verbose: bool = None,
        sort: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.members.list

Auditing

Calling this method generates the following auditing event.

iam-groups.members.list

Request

Instantiate the ListAccessGroupMembersOptions struct and set the fields to provide parameter values for the ListAccessGroupMembers method.

Use the ListAccessGroupMembersOptions.Builder to create a ListAccessGroupMembersOptions object that contains the parameter values for the listAccessGroupMembers method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Query Parameters

membership_type
string
Filters members by membership type. Membership type can be either static, dynamic or all. static lists those members explicitly added to the access group, dynamic lists those members part of access group via dynamic rules at the moment. all lists both static and dynamic members.

Default: static
limit
integer
Return up to this limit of results where limit is between 0 and 100.

Possible values: value ≤ 100
Default: 50
offset
integer
The offset of the first result item to be returned.

Default: 0
type
string
Filter the results by member type.
verbose
boolean
Return user's email and name for each user ID or the name for each service ID or trusted profile.

Default: false
sort
string
If verbose is true, sort the results by id, name, or email.

parameter

WithContext method only

ListAccessGroupMembersOptions

The ListAccessGroupMembers options.

ListAccessGroupMembersOptions

The listAccessGroupMembers options.

parameters

accessGroupId
Required*
string
The access group identifier.
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.
membershipType
string
Filters members by membership type. Membership type can be either static, dynamic or all. static lists those members explicitly added to the access group, dynamic lists those members part of access group via dynamic rules at the moment. all lists both static and dynamic members.

Default: static
limit
number
Return up to this limit of results where limit is between 0 and 100.

Possible values: value ≤ 100
offset
number
The offset of the first result item to be returned.
type
string
Filter the results by member type.
verbose
boolean
Return user's email and name for each user ID or the name for each service ID or trusted profile.

Default: false
sort
string
If verbose is true, sort the results by id, name, or email.

parameters

access_group_id
Required*
str
The access group identifier.
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.
membership_type
str
Filters members by membership type. Membership type can be either static, dynamic or all. static lists those members explicitly added to the access group, dynamic lists those members part of access group via dynamic rules at the moment. all lists both static and dynamic members.

Default: static
limit
int
Return up to this limit of results where limit is between 0 and 100.

Possible values: value ≤ 100
offset
int
The offset of the first result item to be returned.
type
str
Filter the results by member type.
verbose
bool
Return user's email and name for each user ID or the name for each service ID or trusted profile.

Default: false
sort
str
If verbose is true, sort the results by id, name, or email.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/groups/{access_group_id}/members"

Example request

listAccessGroupMembersOptions := &iamaccessgroupsv2.ListAccessGroupMembersOptions{
  AccessGroupID: &accessGroupIDLink,
}

pager, err := iamAccessGroupsService.NewAccessGroupMembersPager(listAccessGroupMembersOptions)
if err != nil {
  panic(err)
}

var allResults []iamaccessgroupsv2.ListGroupMembersResponseMember
for pager.HasNext() {
  nextPage, err := pager.GetNext()
  if err != nil {
    panic(err)
  }
  allResults = append(allResults, nextPage...)
}
b, _ := json.MarshalIndent(allResults, "", "  ")
fmt.Println(string(b))

Example request

ListAccessGroupMembersOptions listAccessGroupMembersOptions = new ListAccessGroupMembersOptions.Builder()
    .accessGroupId(testGroupId).build();

AccessGroupMembersPager pager = new AccessGroupMembersPager(iamAccessGroupsService,
    listAccessGroupMembersOptions);
List<ListGroupMembersResponseMember> allResults = new ArrayList<>();
while (pager.hasNext()) {
  List<ListGroupMembersResponseMember> nextPage = pager.getNext();
  allResults.addAll(nextPage);
}

System.out.println(GsonSingleton.getGson().toJson(allResults));

Example request

const params = {
  accessGroupId: testGroupId,
};

const allResults = [];
try {
  const pager = new IamAccessGroupsV2.AccessGroupMembersPager(iamAccessGroupsService, params);
  while (pager.hasNext()) {
    const nextPage = await pager.getNext();
    expect(nextPage).not.toBeNull();
    allResults.push(...nextPage);
  }
  console.log(JSON.stringify(allResults, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

all_results = []
pager = AccessGroupMembersPager(
  client=iam_access_groups_service,
  access_group_id=test_group_id,
)
while pager.has_next():
  next_page = pager.get_next()
  assert next_page is not None
  all_results.extend(next_page)

print(json.dumps(all_results, indent=2))

Response

Response Body

GroupMembersList

The members of a group.

GroupMembersList

The members of a group.

GroupMembersList

The members of a group.

GroupMembersList

The members of a group.

GroupMembersList

The members of a group.

Status Code

200
Success.
401
Invalid Access Token.
403
Access Denied.
404
Not Found.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 200

{
  "limit": 50,
  "offset": 0,
  "total_count": 2,
  "first": {
    "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members?limit=50&verbose=true&membership_type=all"
  },
  "last": {
    "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members?offset=0&limit=50&verbose=true&membership_type=all"
  },
  "members": [
    {
      "iam_id": "IBM_ID",
      "type": "user",
      "membership_type": "static",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members/IAM_ID",
      "name": "John Doe",
      "email": "john.doe@ibm.com",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID"
    },
    {
      "iam_id": "IBM_ID",
      "type": "user",
      "membership_type": "dynamic",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members/IAM_ID",
      "name": "John Doe",
      "email": "john.doe@ibm.com",
      "created_at": "2019-01-01T01:01:00Z",
      "expires_at": "2019-01-01T02:01:00Z",
      "created_by_id": "CREATOR_ID"
    },
    {
      "iam_id": "SERVICE_ID",
      "type": "service",
      "membership_type": "static",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members/SERVICE_ID",
      "name": "Service ID 1",
      "description": "This is the description of the service id.",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID"
    },
    {
      "iam_id": "PROFILE_ID",
      "type": "profile",
      "membership_type": "static",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members/PROFILE_ID",
      "name": "Trusted Profile 1",
      "description": "This is the description of the trusted profile.",
      "created_at": "2022-01-27T09:18:52Z",
      "created_by_id": "CREATOR_ID"
    }
  ]
}

Success example

{
  "limit": 50,
  "offset": 0,
  "total_count": 2,
  "first": {
    "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members?limit=50&verbose=true&membership_type=all"
  },
  "last": {
    "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members?offset=0&limit=50&verbose=true&membership_type=all"
  },
  "members": [
    {
      "iam_id": "IBM_ID",
      "type": "user",
      "membership_type": "static",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members/IAM_ID",
      "name": "John Doe",
      "email": "john.doe@ibm.com",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID"
    },
    {
      "iam_id": "IBM_ID",
      "type": "user",
      "membership_type": "dynamic",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members/IAM_ID",
      "name": "John Doe",
      "email": "john.doe@ibm.com",
      "created_at": "2019-01-01T01:01:00Z",
      "expires_at": "2019-01-01T02:01:00Z",
      "created_by_id": "CREATOR_ID"
    },
    {
      "iam_id": "SERVICE_ID",
      "type": "service",
      "membership_type": "static",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members/SERVICE_ID",
      "name": "Service ID 1",
      "description": "This is the description of the service id.",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID"
    },
    {
      "iam_id": "PROFILE_ID",
      "type": "profile",
      "membership_type": "static",
      "href": "{endpoint_url}/v2/groups/ACCESS_GROUP_ID/members/PROFILE_ID",
      "name": "Trusted Profile 1",
      "description": "This is the description of the trusted profile.",
      "created_at": "2022-01-27T09:18:52Z",
      "created_by_id": "CREATOR_ID"
    }
  ]
}

Status 401

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Status 403

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Status 404

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_found",
      "message": "Failed to find the specified access group: <id>"
    }
  ],
  "status_code": 404
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_found",
      "message": "Failed to find the specified access group: <id>"
    }
  ],
  "status_code": 404
}

Status 500

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Status 503

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

This HEAD operation determines if a given iam_id is present in a group either explicitly or via dynamic rules. 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 /v2/groups/{access_group_id}/members/{iam_id}

(iamAccessGroups *IamAccessGroupsV2) IsMemberOfAccessGroup(isMemberOfAccessGroupOptions *IsMemberOfAccessGroupOptions) (response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) IsMemberOfAccessGroupWithContext(ctx context.Context, isMemberOfAccessGroupOptions *IsMemberOfAccessGroupOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> isMemberOfAccessGroup(IsMemberOfAccessGroupOptions isMemberOfAccessGroupOptions)

isMemberOfAccessGroup(params)

is_member_of_access_group(self,
        access_group_id: str,
        iam_id: str,
        *,
        transaction_id: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.members.read

Auditing

Calling this method generates the following auditing event.

iam-groups.member.read

Request

Instantiate the IsMemberOfAccessGroupOptions struct and set the fields to provide parameter values for the IsMemberOfAccessGroup method.

Use the IsMemberOfAccessGroupOptions.Builder to create a IsMemberOfAccessGroupOptions object that contains the parameter values for the isMemberOfAccessGroup method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.
iam_id
Required*
string
The IAM identifier.

parameter

WithContext method only

IsMemberOfAccessGroupOptions

The IsMemberOfAccessGroup options.

IsMemberOfAccessGroupOptions

The isMemberOfAccessGroup options.

parameters

accessGroupId
Required*
string
The access group identifier.
iamId
Required*
string
The IAM identifier.
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

access_group_id
Required*
str
The access group identifier.
iam_id
Required*
str
The IAM identifier.
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

curl -X HEAD --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/groups/{access_group_id}/members/{iam_id}"

Example request

isMemberOfAccessGroupOptions := iamAccessGroupsService.NewIsMemberOfAccessGroupOptions(
  accessGroupIDLink,
  "IBMid-user1",
)

response, err := iamAccessGroupsService.IsMemberOfAccessGroup(isMemberOfAccessGroupOptions)
if err != nil {
  panic(err)
}
if response.StatusCode != 204 {
  fmt.Printf("\nUnexpected response status code received from IsMemberOfAccessGroup(): %d\n", response.StatusCode)
}

Example request

IsMemberOfAccessGroupOptions isMemberOfAccessGroupOptions = new IsMemberOfAccessGroupOptions.Builder()
  .accessGroupId(testGroupId)
  .iamId("IBMid-user1")
  .build();

Response<Void> response = iamAccessGroupsService.isMemberOfAccessGroup(isMemberOfAccessGroupOptions).execute();

Example request

const params = {
  accessGroupId: testGroupId,
  iamId: 'IBMid-user1',
};

try {
  await iamAccessGroupsService.isMemberOfAccessGroup(params);
} catch (err) {
  console.warn(err);
}

Example request

response = iam_access_groups_service.is_member_of_access_group(
  access_group_id=test_group_id,
  iam_id='IBMid-user1'
)

Response

Status Code

204
Membership exists.
401
Invalid Access Token.
403
Access Denied.
404
Membership not found.
500
Internal Server Error.
503
Service Unavailable.

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. Dynamic member cannot be deleted using this API. Dynamic rules needs to be adjusted to delete dynamic members.

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

(iamAccessGroups *IamAccessGroupsV2) RemoveMemberFromAccessGroup(removeMemberFromAccessGroupOptions *RemoveMemberFromAccessGroupOptions) (response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) RemoveMemberFromAccessGroupWithContext(ctx context.Context, removeMemberFromAccessGroupOptions *RemoveMemberFromAccessGroupOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> removeMemberFromAccessGroup(RemoveMemberFromAccessGroupOptions removeMemberFromAccessGroupOptions)

removeMemberFromAccessGroup(params)

remove_member_from_access_group(self,
        access_group_id: str,
        iam_id: str,
        *,
        transaction_id: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.members.delete

Auditing

Calling this method generates the following auditing event.

iam-groups.member.delete

Request

Instantiate the RemoveMemberFromAccessGroupOptions struct and set the fields to provide parameter values for the RemoveMemberFromAccessGroup method.

Use the RemoveMemberFromAccessGroupOptions.Builder to create a RemoveMemberFromAccessGroupOptions object that contains the parameter values for the removeMemberFromAccessGroup method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.
iam_id
Required*
string
The IAM identifier.

parameter

WithContext method only

RemoveMemberFromAccessGroupOptions

The RemoveMemberFromAccessGroup options.

RemoveMemberFromAccessGroupOptions

The removeMemberFromAccessGroup options.

parameters

accessGroupId
Required*
string
The access group identifier.
iamId
Required*
string
The IAM identifier.
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

access_group_id
Required*
str
The access group identifier.
iam_id
Required*
str
The IAM identifier.
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/groups/{access_group_id}/members/{iam_id}"

Example request

removeMemberFromAccessGroupOptions := iamAccessGroupsService.NewRemoveMemberFromAccessGroupOptions(
  accessGroupIDLink,
  "IBMid-user1",
)

response, err := iamAccessGroupsService.RemoveMemberFromAccessGroup(removeMemberFromAccessGroupOptions)
if err != nil {
  panic(err)
}
if response.StatusCode != 204 {
  fmt.Printf("\nUnexpected response status code received from RemoveMemberFromAccessGroup(): %d\n", response.StatusCode)
}


removeMemberFromAccessGroupOptions := iamAccessGroupsService.NewRemoveMemberFromAccessGroupOptions(
  accessGroupIDLink,
  "iam-ServiceId-123",
)

response, err := iamAccessGroupsService.RemoveMemberFromAccessGroup(removeMemberFromAccessGroupOptions)
if err != nil {
  panic(err)
}
if response.StatusCode != 204 {
  fmt.Printf("\nUnexpected response status code received from RemoveMemberFromAccessGroup(): %d\n", response.StatusCode)
}


removeMemberFromAccessGroupOptions := iamAccessGroupsService.NewRemoveMemberFromAccessGroupOptions(
  accessGroupIDLink,
  testProfileID,
)

response, err := iamAccessGroupsService.RemoveMemberFromAccessGroup(removeMemberFromAccessGroupOptions)
if err != nil {
  panic(err)
}
if response.StatusCode != 204 {
  fmt.Printf("\nUnexpected response status code received from RemoveMemberFromAccessGroup(): %d\n", response.StatusCode)
}

Example request

RemoveMemberFromAccessGroupOptions removeMemberFromAccessGroupOptions = new RemoveMemberFromAccessGroupOptions.Builder()
  .accessGroupId(testGroupId)
  .iamId("IBMid-user1")
  .build();

Response<Void> response = iamAccessGroupsService.removeMemberFromAccessGroup(removeMemberFromAccessGroupOptions).execute();

Example request

const params = {
  accessGroupId: testGroupId,
  iamId: 'IBMid-user1',
};

try {
  await iamAccessGroupsService.removeMemberFromAccessGroup(params);
} catch (err) {
  console.warn(err);
}

Example request

response = iam_access_groups_service.remove_member_from_access_group(
  access_group_id=test_group_id,
  iam_id='IBMid-user1'
)

Response

Status Code

204
Membership deleted.
401
Invalid Access Token.
403
Access Denied.
404
Membership not found.
405
Method Not Allowed.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 401

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Status 403

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Status 404

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_found",
      "message": "Failed to find the specified access group: <id>"
    }
  ],
  "status_code": 404
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "group_not_found",
      "message": "Failed to find the specified access group: <id>"
    }
  ],
  "status_code": 404
}

Status 405

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot delete group membership for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot delete group membership for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}

Status 500

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Status 503

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Remove multiple members from a group using this API. On a successful call, this API will always return 207. It is the caller's responsibility to iterate across the body to determine successful deletion of each member. This API request payload can delete up to 50 members per call. This API doesnt delete dynamic members accessing the access group via dynamic rules.

POST /v2/groups/{access_group_id}/members/delete

(iamAccessGroups *IamAccessGroupsV2) RemoveMembersFromAccessGroup(removeMembersFromAccessGroupOptions *RemoveMembersFromAccessGroupOptions) (result *DeleteGroupBulkMembersResponse, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) RemoveMembersFromAccessGroupWithContext(ctx context.Context, removeMembersFromAccessGroupOptions *RemoveMembersFromAccessGroupOptions) (result *DeleteGroupBulkMembersResponse, response *core.DetailedResponse, err error)

ServiceCall<DeleteGroupBulkMembersResponse> removeMembersFromAccessGroup(RemoveMembersFromAccessGroupOptions removeMembersFromAccessGroupOptions)

removeMembersFromAccessGroup(params)

remove_members_from_access_group(self,
        access_group_id: str,
        *,
        members: List[str] = None,
        transaction_id: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.members.delete

Auditing

Calling this method generates the following auditing event.

iam-groups.member.delete

Request

Instantiate the RemoveMembersFromAccessGroupOptions struct and set the fields to provide parameter values for the RemoveMembersFromAccessGroup method.

Use the RemoveMembersFromAccessGroupOptions.Builder to create a RemoveMembersFromAccessGroupOptions object that contains the parameter values for the removeMembersFromAccessGroup method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Request Body

Required*

DeleteGroupBulkMembersRequest

The members to remove from an access group.

Examples:

View

parameter

WithContext method only

RemoveMembersFromAccessGroupOptions

The RemoveMembersFromAccessGroup options.

RemoveMembersFromAccessGroupOptions

The removeMembersFromAccessGroup options.

parameters

accessGroupId
Required*
string
The access group identifier.
members
string[]
The iam_ids to remove from the access group. This field has a limit of 50 iam_ids.

Examples:
value
_source
_lines
_html
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

access_group_id
Required*
str
The access group identifier.
members
List[str]
The iam_ids to remove from the access group. This field has a limit of 50 iam_ids.

Examples:
value
_source
_lines
_html
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "members": [ "IBMId-user1", "iam-ServiceId-123", "iam-Profile-123" ] }'   "{base_url}/v2/groups/{access_group_id}/members/delete"

Example request

RemoveMembersFromAccessGroupOptions removeMembersFromAccessGroupOptions = new RemoveMembersFromAccessGroupOptions.Builder()
  .accessGroupId(testGroupId)
  .addMembers("iam-ServiceId-123")
  .build();

Response<DeleteGroupBulkMembersResponse> response = iamAccessGroupsService.removeMembersFromAccessGroup(removeMembersFromAccessGroupOptions).execute();
DeleteGroupBulkMembersResponse deleteGroupBulkMembersResponse = response.getResult();

System.out.println(deleteGroupBulkMembersResponse);


RemoveMembersFromAccessGroupOptions removeMembersFromAccessGroupOptions = new RemoveMembersFromAccessGroupOptions.Builder()
  .accessGroupId(testGroupId)
  .addMembers(testProfileId)
  .build();

Response<DeleteGroupBulkMembersResponse> response = iamAccessGroupsService.removeMembersFromAccessGroup(removeMembersFromAccessGroupOptions).execute();
DeleteGroupBulkMembersResponse deleteGroupBulkMembersResponse = response.getResult();

System.out.println(deleteGroupBulkMembersResponse);

Example request

const params = {
  accessGroupId: testGroupId,
  members: ['iam-ServiceId-123']
};

try {
  const res = await iamAccessGroupsService.removeMembersFromAccessGroup(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}


const params = {
  accessGroupId: testGroupId,
  members: [profileId]
};

try {
  const res = await iamAccessGroupsService.removeMembersFromAccessGroup(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

delete_group_bulk_members_response = iam_access_groups_service.remove_members_from_access_group(
  access_group_id=test_group_id,
  members=['iam-ServiceId-123']
).get_result()

print(json.dumps(delete_group_bulk_members_response, indent=2))


delete_group_bulk_members_response = iam_access_groups_service.remove_members_from_access_group(
  access_group_id=test_group_id,
  members=[test_profile_id]
).get_result()

print(json.dumps(delete_group_bulk_members_response, indent=2))

Response

Response Body

DeleteGroupBulkMembersResponse

The access group id and the members removed from it.

DeleteGroupBulkMembersResponse

The access group id and the members removed from it.

DeleteGroupBulkMembersResponse

The access group id and the members removed from it.

DeleteGroupBulkMembersResponse

The access group id and the members removed from it.

DeleteGroupBulkMembersResponse

The access group id and the members removed from it.

Status Code

207
There is a multiple status response. Please check the response body.
400
Bad Input (Including duplicate members in request).
401
Invalid Access Token.
403
Access Denied.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 207

{
  "access_group_id": "ACCESS_GROUP_ID",
  "members": [
    {
      "iam_id": "IBM_ID",
      "status_code": 204
    },
    {
      "iam_id": "SERVICE_ID",
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Failed to find the membership"
        }
      ],
      "status_code": 404
    }
  ]
}

Success example

{
  "access_group_id": "ACCESS_GROUP_ID",
  "members": [
    {
      "iam_id": "IBM_ID",
      "status_code": 204
    },
    {
      "iam_id": "SERVICE_ID",
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Failed to find the membership"
        }
      ],
      "status_code": 404
    }
  ]
}

Status 400

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_payload",
      "message": "Payload contains invalid/missing data."
    }
  ],
  "status_code": 400
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_payload",
      "message": "Payload contains invalid/missing data."
    }
  ],
  "status_code": 400
}

Status 401

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_token",
      "message": "The token is either missing or invalid"
    }
  ],
  "status_code": 401
}

Status 403

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "forbidden",
      "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
    }
  ],
  "status_code": 403
}

Status 500

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "internal_server_error",
      "message": "Internal Server Error"
    }
  ],
  "status_code": 500
}

Status 503

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "service_unavailable",
      "message": "Service Temporarily Unavailable"
    }
  ],
  "status_code": 503
}

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 /v2/groups/_allgroups/members/{iam_id}

(iamAccessGroups *IamAccessGroupsV2) RemoveMemberFromAllAccessGroups(removeMemberFromAllAccessGroupsOptions *RemoveMemberFromAllAccessGroupsOptions) (result *DeleteFromAllGroupsResponse, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) RemoveMemberFromAllAccessGroupsWithContext(ctx context.Context, removeMemberFromAllAccessGroupsOptions *RemoveMemberFromAllAccessGroupsOptions) (result *DeleteFromAllGroupsResponse, response *core.DetailedResponse, err error)

ServiceCall<DeleteFromAllGroupsResponse> removeMemberFromAllAccessGroups(RemoveMemberFromAllAccessGroupsOptions removeMemberFromAllAccessGroupsOptions)

removeMemberFromAllAccessGroups(params)

remove_member_from_all_access_groups(self,
        account_id: str,
        iam_id: str,
        *,
        transaction_id: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam-groups.members.delete

Auditing

Calling this method generates the following auditing event.

iam-groups.member.delete

Request

Instantiate the RemoveMemberFromAllAccessGroupsOptions struct and set the fields to provide parameter values for the RemoveMemberFromAllAccessGroups method.

Use the RemoveMemberFromAllAccessGroupsOptions.Builder to create a RemoveMemberFromAllAccessGroupsOptions object that contains the parameter values for the removeMemberFromAllAccessGroups method.

Custom Headers

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

Path Parameters

iam_id
Required*
string
The IAM identifier.

Query Parameters

account_id
Required*
string
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.

parameter

WithContext method only

RemoveMemberFromAllAccessGroupsOptions

The RemoveMemberFromAllAccessGroups options.

RemoveMemberFromAllAccessGroupsOptions

The removeMemberFromAllAccessGroups options.

parameters

accountId
Required*
string
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
iamId
Required*
string
The IAM identifier.
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

account_id
Required*
str
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
iam_id
Required*
str
The IAM identifier.
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/groups/_allgroups/members/{iam_id}?account_id={account_id}"

Example request

removeMemberFromAllAccessGroupsOptions := iamAccessGroupsService.NewRemoveMemberFromAllAccessGroupsOptions(
  testAccountID,
  "IBMid-user1",
)

deleteFromAllGroupsResponse, response, err := iamAccessGroupsService.RemoveMemberFromAllAccessGroups(removeMemberFromAllAccessGroupsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(deleteFromAllGroupsResponse, "", "  ")
fmt.Println(string(b))

Example request

RemoveMemberFromAllAccessGroupsOptions removeMemberFromAllAccessGroupsOptions = new RemoveMemberFromAllAccessGroupsOptions.Builder()
  .accountId(testAccountId)
  .iamId("IBMid-user1")
  .build();

Response<DeleteFromAllGroupsResponse> response = iamAccessGroupsService.removeMemberFromAllAccessGroups(removeMemberFromAllAccessGroupsOptions).execute();
DeleteFromAllGroupsResponse deleteFromAllGroupsResponse = response.getResult();

System.out.println(deleteFromAllGroupsResponse);

Example request

const params = {
  accountId: testAccountId,
  iamId: 'IBMid-user1',
};

try {
  const res = await iamAccessGroupsService.removeMemberFromAllAccessGroups(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

delete_from_all_groups_response = iam_access_groups_service.remove_member_from_all_access_groups(
  account_id=test_account_id,
  iam_id='IBMid-user1'
).get_result()

print(json.dumps(delete_from_all_groups_response, indent=2))

Response

Response Body

DeleteFromAllGroupsResponse

The response from the delete member from access groups request.

DeleteFromAllGroupsResponse

The response from the delete member from access groups request.

Introduction

Endpoint URLs

Authentication

Auditing

Error handling

Additional headers

Pagination

Sorting

Rate limiting

Related APIs

Methods

Create an access group

Authorization

Auditing

Request

Custom Headers

Transaction-Id

Query Parameters

account_id

Request Body

name

description

parameter

ctx

CreateAccessGroupOptions

AccountID

Name

Description

TransactionID

CreateAccessGroupOptions

accountId

name

description

transactionId

parameters

accountId

name

description

transactionId

parameters

account_id

name

description

transaction_id

Response

Response Body

id

name

description

created_at

created_by_id

last_modified_at

last_modified_by_id

href

is_federated

Group

ID

Name

Description

AccountID

CreatedAt

CreatedByID

LastModifiedAt

LastModifiedByID

Href

IsFederated

Group

id

name

description

accountId

createdAt

createdById

lastModifiedAt

lastModifiedById

href

isFederated

Group

id

name