Introduction

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

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

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

Installing the Python SDK

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

View on GitHub

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.

Methods

Create an access group

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

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.

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.

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.

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

  • 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 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.

The access group to create.

Examples:
View

WithContext method only

The CreateAccessGroup options.

The createAccessGroup options.

parameters

  • 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.

  • 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
  • Assign an optional description for the access group. This field has a limit of 250 characters.

    Examples:
    value
    _source
    _lines
    _html
  • 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 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.

  • 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
  • Assign an optional description for the access group. This field has a limit of 250 characters.

    Examples:
    value
    _source
    _lines
    _html
  • 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.

  • 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}"
  • 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))
  • 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);
  • 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);
    }
  • 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

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

Status Code

  • Group Created.

  • Bad Request

  • Invalid Access Token.

  • Access Denied.

  • Group Name Conflicted.

  • Internal Server Error.

  • Service Unavailable.

Example responses
  • {
      "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"
    }
  • {
      "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"
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

List access groups

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

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.

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.

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.

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

  • 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 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.

  • Return groups for member ID (IBMid, service ID or trusted profile ID).

  • 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 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

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

    Possible values: value ≤ 100

    Default: 50

  • The offset of the first result item to be returned.

    Default: 0

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

    Default: name

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

    Default: false

  • If hide_public_access is true, do not include the Public Access Group in the results.

    Default: false

WithContext method only

The ListAccessGroups options.

The listAccessGroups options.

parameters

  • 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.

  • 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.

  • Return groups for member ID (IBMid, service ID or trusted profile ID).

  • 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

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

    Possible values: value ≤ 100

  • The offset of the first result item to be returned.

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

    Default: name

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

    Default: false

  • If hide_public_access is true, do not include the Public Access Group in the results.

    Default: false

parameters

  • 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.

  • 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.

  • Return groups for member ID (IBMid, service ID or trusted profile ID).

  • 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

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

    Possible values: value ≤ 100

  • The offset of the first result item to be returned.

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

    Default: name

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

    Default: false

  • If hide_public_access is true, do not include the Public Access Group in the results.

    Default: false

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/groups?account_id={account_id}"
  • 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))
  • 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));
  • 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);
    }
  • 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

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

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

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

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

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

Status Code

  • Success.

  • Invalid Access Token.

  • Access Denied.

  • Internal Server Error.

  • Service Unavailable.

Example responses
  • {
      "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
        }
      ]
    }
  • {
      "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
        }
      ]
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Get an access group

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

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.

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.

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.

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

  • 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

  • The access group identifier.

Query Parameters

  • 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

WithContext method only

The GetAccessGroup options.

The getAccessGroup options.

parameters

  • The access group identifier.

  • 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.

  • 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

  • The access group identifier.

  • 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.

  • 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

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/groups/{access_group_id}"
  • getAccessGroupOptions := iamAccessGroupsService.NewGetAccessGroupOptions(
      accessGroupIDLink,
    )
    
    group, response, err := iamAccessGroupsService.GetAccessGroup(getAccessGroupOptions)
    if err != nil {
      panic(err)
    }
    b, _ := json.MarshalIndent(group, "", "  ")
    fmt.Println(string(b))
  • GetAccessGroupOptions getAccessGroupOptions = new GetAccessGroupOptions.Builder()
      .accessGroupId(testGroupId)
      .build();
    
    Response<Group> response = iamAccessGroupsService.getAccessGroup(getAccessGroupOptions).execute();
    Group group = response.getResult();
    
    System.out.println(group);
  • 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);
    }
  • 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

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

Status Code

  • Get Successful.

  • Invalid Access Token.

  • Access Denied.

  • Not Found.

  • Internal Server Error.

  • Service Unavailable.

Example responses
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Update an access group

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

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).

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).

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).

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

  • The current revision number of the group being updated. This can be found in the Create/Get access group response ETag header.

  • 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

  • The access group identifier.

The access group to update.

Examples:
View

WithContext method only

The UpdateAccessGroup options.

The updateAccessGroup options.

parameters

  • The access group identifier.

  • The current revision number of the group being updated. This can be found in the Create/Get access group response ETag header.

  • 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
  • Assign an optional description for the access group. This field has a limit of 250 characters.

    Examples:
    value
    _source
    _lines
    _html
  • 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

  • The access group identifier.

  • The current revision number of the group being updated. This can be found in the Create/Get access group response ETag header.

  • 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
  • Assign an optional description for the access group. This field has a limit of 250 characters.

    Examples:
    value
    _source
    _lines
    _html
  • 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.

  • 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}"
  • 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))
  • 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);
  • 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);
    }
  • 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

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

Status Code

  • Group Updated.

  • Bad Request.

  • Invalid Access Token.

  • Access Denied.

  • Not Found.

  • Method Not Allowed.

  • Group Name Conflicted.

  • Precondition Failed.

  • Internal Server Error.

  • Service Unavailable.

Example responses
  • {
      "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"
    }
  • {
      "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"
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot update group for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot update group for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "incorrect_etag",
          "message": "If-Match header contains incorrect/invalid etag."
        }
      ],
      "status_code": 412
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "incorrect_etag",
          "message": "If-Match header contains incorrect/invalid etag."
        }
      ],
      "status_code": 412
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Delete an access group

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

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.

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.

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.

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

  • 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

  • The access group identifier.

Query Parameters

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

    Default: false

WithContext method only

The DeleteAccessGroup options.

The deleteAccessGroup options.

parameters

  • The access group identifier.

  • 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.

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

    Default: false

parameters

  • The access group identifier.

  • 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.

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

    Default: false

  • curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/groups/{access_group_id}"
  • 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)
    }
  • DeleteAccessGroupOptions deleteAccessGroupOptions = new DeleteAccessGroupOptions.Builder()
      .accessGroupId(testGroupId)
      .build();
    
    Response<Void> response = iamAccessGroupsService.deleteAccessGroup(deleteAccessGroupOptions).execute();
  • const params = {
      accessGroupId: testGroupId,
    };
    
    try {
      await iamAccessGroupsService.deleteAccessGroup(params);
    } catch (err) {
      console.warn(err);
    }
  • response = iam_access_groups_service.delete_access_group(
      access_group_id=test_group_id
    )

Response

Status Code

  • Delete Successful.

  • Invalid Access Token.

  • Access Denied.

  • Not Found.

  • Method Not Allowed.

  • Group Not Empty.

  • Internal Server Error.

  • Service Unavailable.

Example responses
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot delete group for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot delete group for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_empty",
          "message": "Access group is not empty: <id>"
        }
      ],
      "status_code": 409
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_empty",
          "message": "Access group is not empty: <id>"
        }
      ],
      "status_code": 409
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Add members to an access group

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.

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.

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.

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.

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

  • 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

  • The access group identifier.

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

Examples:
View

WithContext method only

The AddMembersToAccessGroup options.

The addMembersToAccessGroup options.

parameters

  • The access group identifier.

  • An array of member objects to add to an access group.

    Examples:
    value
    _source
    _lines
    _html
  • 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

  • The access group identifier.

  • An array of member objects to add to an access group.

    Examples:
    value
    _source
    _lines
    _html
  • 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.

  • 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"
  • 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))
  • 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);
  • 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);
    }
  • 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

The members added to an access group.

The members added to an access group.

The members added to an access group.

The members added to an access group.

The members added to an access group.

Status Code

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

  • Bad Input (Including duplicate members in request).

  • Invalid Access Token.

  • Access Denied.

  • Not Found.

  • Method Not Allowed.

  • Internal Server Error.

  • Service Unavailable.

Example responses
  • {
      "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
        }
      ]
    }
  • {
      "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
        }
      ]
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "membership_not_found",
          "message": "Failed to find the membership"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "membership_not_found",
          "message": "Failed to find the membership"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot add members for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot add members for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

List access group members

List all members of a given group using this API. Parameters for pagination and sorting can be used to filter the results. The most useful query parameter may be the verbose flag. If verbose=true, user, 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.

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.

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.

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.

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

  • 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

  • The access group identifier.

Query Parameters

  • 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

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

    Possible values: value ≤ 100

    Default: 50

  • The offset of the first result item to be returned.

    Default: 0

  • Filter the results by member type.

  • Return user's email and name for each user ID or the name for each service ID or trusted profile.

    Default: false

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

WithContext method only

The ListAccessGroupMembers options.

The listAccessGroupMembers options.

parameters

  • The access group identifier.

  • 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.

  • 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

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

    Possible values: value ≤ 100

  • The offset of the first result item to be returned.

  • Filter the results by member type.

  • Return user's email and name for each user ID or the name for each service ID or trusted profile.

    Default: false

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

parameters

  • The access group identifier.

  • 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.

  • 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

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

    Possible values: value ≤ 100

  • The offset of the first result item to be returned.

  • Filter the results by member type.

  • Return user's email and name for each user ID or the name for each service ID or trusted profile.

    Default: false

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

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v2/groups/{access_group_id}/members"
  • 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))
  • 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));
  • 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);
    }
  • 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

The members of a group.

The members of a group.

The members of a group.

The members of a group.

The members of a group.

Status Code

  • Success.

  • Invalid Access Token.

  • Access Denied.

  • Not Found.

  • Internal Server Error.

  • Service Unavailable.

Example responses
  • {
      "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"
        }
      ]
    }
  • {
      "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"
        }
      ]
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Check membership in an access group

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.

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.

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.

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.

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

  • 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

  • The access group identifier.

  • The IAM identifier.

WithContext method only

The IsMemberOfAccessGroup options.

The isMemberOfAccessGroup options.

parameters

  • The access group identifier.

  • The IAM identifier.

  • 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

  • The access group identifier.

  • The IAM identifier.

  • 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.

  • curl -X HEAD --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/groups/{access_group_id}/members/{iam_id}"
  • 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)
    }
  • IsMemberOfAccessGroupOptions isMemberOfAccessGroupOptions = new IsMemberOfAccessGroupOptions.Builder()
      .accessGroupId(testGroupId)
      .iamId("IBMid-user1")
      .build();
    
    Response<Void> response = iamAccessGroupsService.isMemberOfAccessGroup(isMemberOfAccessGroupOptions).execute();
  • const params = {
      accessGroupId: testGroupId,
      iamId: 'IBMid-user1',
    };
    
    try {
      await iamAccessGroupsService.isMemberOfAccessGroup(params);
    } catch (err) {
      console.warn(err);
    }
  • response = iam_access_groups_service.is_member_of_access_group(
      access_group_id=test_group_id,
      iam_id='IBMid-user1'
    )

Response

Status Code

  • Membership exists.

  • Invalid Access Token.

  • Access Denied.

  • Membership not found.

  • Internal Server Error.

  • Service Unavailable.

Delete member from an access group

Remove one member from a group using this API. If the operation is successful, only a 204 - No Content response with no body is returned. However, if any error occurs, the standard error format will be returned. Dynamic member cannot be deleted using this API. Dynamic rules needs to be adjusted to delete dynamic members.

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.

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.

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.

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

  • 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

  • The access group identifier.

  • The IAM identifier.

WithContext method only

The RemoveMemberFromAccessGroup options.

The removeMemberFromAccessGroup options.

parameters

  • The access group identifier.

  • The IAM identifier.

  • 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

  • The access group identifier.

  • The IAM identifier.

  • 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.

  • curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v2/groups/{access_group_id}/members/{iam_id}"
  • 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)
    }
  • RemoveMemberFromAccessGroupOptions removeMemberFromAccessGroupOptions = new RemoveMemberFromAccessGroupOptions.Builder()
      .accessGroupId(testGroupId)
      .iamId("IBMid-user1")
      .build();
    
    Response<Void> response = iamAccessGroupsService.removeMemberFromAccessGroup(removeMemberFromAccessGroupOptions).execute();
  • const params = {
      accessGroupId: testGroupId,
      iamId: 'IBMid-user1',
    };
    
    try {
      await iamAccessGroupsService.removeMemberFromAccessGroup(params);
    } catch (err) {
      console.warn(err);
    }
  • response = iam_access_groups_service.remove_member_from_access_group(
      access_group_id=test_group_id,
      iam_id='IBMid-user1'
    )

Response

Status Code

  • Membership deleted.

  • Invalid Access Token.

  • Access Denied.

  • Membership not found.

  • Method Not Allowed.

  • Internal Server Error.

  • Service Unavailable.

Example responses
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot delete group membership for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Delete members from an access group

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.

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.

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.

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.

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

  • 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

  • The access group identifier.

The members to remove from an access group.

Examples:
View

WithContext method only

The RemoveMembersFromAccessGroup options.

The removeMembersFromAccessGroup options.

parameters

  • The access group identifier.

  • The iam_ids to remove from the access group. This field has a limit of 50 iam_ids.

    Examples:
    value
    _source
    _lines
    _html
  • 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

  • The access group identifier.

  • The iam_ids to remove from the access group. This field has a limit of 50 iam_ids.

    Examples:
    value
    _source
    _lines
    _html
  • 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.

  • 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"
  • 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);
  • 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);
    }
  • 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

The access group id and the members removed from it.

The access group id and the members removed from it.

The access group id and the members removed from it.

The access group id and the members removed from it.

The access group id and the members removed from it.

Status Code

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

  • Bad Input (Including duplicate members in request).

  • Invalid Access Token.

  • Access Denied.

  • Internal Server Error.

  • Service Unavailable.

Example responses
  • {
      "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
        }
      ]
    }
  • {
      "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
        }
      ]
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "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
    }
  • {
      "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
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Delete member from all access groups

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

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.

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.

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.

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

  • 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

  • The IAM identifier.

Query Parameters

  • 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.

WithContext method only

The RemoveMemberFromAllAccessGroups options.

The removeMemberFromAllAccessGroups options.

parameters

  • 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.

  • The IAM identifier.

  • 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 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.

  • The IAM identifier.

  • 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.

  • 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}"
  • 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))
  • 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);
  • 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);
    }
  • 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

The response from the delete member from access groups request.

The response from the delete member from access groups request.