IAM Access Groups | IBM Cloud API Docs

Introduction

Last updated: 2023-09-08

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.

With access group templates and assignments you can centrally manage access for child accounts in your organization from the root enterprise account. For more information, see Working with template versions and Best practices for assigning access in an enterprise.

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

Installing the Go SDK

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

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

Go get

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

View on GitHub

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

Installing the Java SDK

Maven

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

Gradle

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

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

View on GitHub

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

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

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

Installing the Python SDK

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

View on GitHub

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

Endpoint URLs

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

https://iam.cloud.ibm.com

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

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

Example API request

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

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

Authentication

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

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

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

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

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

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

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

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

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

To retrieve your access token:

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

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();
Copy to clipboard

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({});
Copy to clipboard

Setting client options through external configuration

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

export IAM_ACCESS_GROUPS_APIKEY=<API_KEY>

Example of constructing the service client

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

Auditing

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

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

Error handling

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

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

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

The following table described the potential error codes the API might return.

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

Additional headers

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

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

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

Pagination

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

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

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

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

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

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

Sorting

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

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

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

Rate limiting

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

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

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

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

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

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

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

POST /v2/groups

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

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

ServiceCall<Group> createAccessGroup(CreateAccessGroupOptions createAccessGroupOptions)
Copy to clipboard

createAccessGroup(params)

create_access_group(
        self,
        account_id: str,
        name: str,
        *,
        description: Optional[str] = None,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-groups.groups.create

Auditing

Calling this method generates the following auditing event.

iam-groups.group.create

Request

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

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

Custom Headers

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

Query Parameters

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

Request Body

Required*

CreateGroupRequest

The access group to create.

Examples:

parameter

WithContext method only

CreateAccessGroupOptions

The CreateAccessGroup options.

CreateAccessGroupOptions

The createAccessGroup options.

parameters

accountId
Required*
string
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
name
Required*
string
Give the access group a unique name that doesn't conflict with an existing access group in the account. This field is case-insensitive and has a limit of 100 characters.
Examples:
description
string
Assign an optional description for the access group. This field has a limit of 250 characters.
Examples:
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

account_id
Required*
str
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
name
Required*
str
Give the access group a unique name that doesn't conflict with an existing access group in the account. This field is case-insensitive and has a limit of 100 characters.
Examples:
description
str
Assign an optional description for the access group. This field has a limit of 250 characters.
Examples:
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

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

Example request

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

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

Example request

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

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

System.out.println(group);
Copy to clipboard

Example request

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

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

Example request

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

print(json.dumps(group, indent=2))
Copy to clipboard

Response

Response Body

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Status Code

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

Example responses

Status 201

{
  "id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "name": "Awesome Developers",
  "description": "Group for awesome developers",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS"
}
Copy to clipboard

Success example

{
  "id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "name": "Awesome Developers",
  "description": "Group for awesome developers",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS"
}
Copy to clipboard

Status 400

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

Error example

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

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 409

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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)
Copy to clipboard

listAccessGroups(params)

list_access_groups(
        self,
        account_id: str,
        *,
        transaction_id: Optional[str] = None,
        iam_id: Optional[str] = None,
        search: Optional[str] = None,
        membership_type: Optional[str] = None,
        limit: Optional[int] = None,
        offset: Optional[int] = None,
        sort: Optional[str] = None,
        show_federated: Optional[bool] = None,
        hide_public_access: Optional[bool] = None,
        show_crn: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-groups.groups.list

Auditing

Calling this method generates the following auditing event.

iam-groups.groups.list

Request

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

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

Custom Headers

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

Query Parameters

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

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

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

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

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

Default: false
hide_public_access
boolean
If hide_public_access is true, do not include the Public Access Group in the results.

Default: false
show_crn
boolean
If show_crn is true, group CRN will be included in the response.

Default: false

parameter

WithContext method only

ListAccessGroupsOptions

The ListAccessGroups options.

ListAccessGroupsOptions

The listAccessGroups options.

parameters

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

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

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

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

Default: name
showFederated
boolean
If show_federated is true, each group listed will return an is_federated value that is set to true if rules exist for the group.

Default: false
hidePublicAccess
boolean
If hide_public_access is true, do not include the Public Access Group in the results.

Default: false
showCrn
boolean
If show_crn is true, group CRN will be included in the response.

Default: false

parameters

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

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

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

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

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

Default: false
hide_public_access
bool
If hide_public_access is true, do not include the Public Access Group in the results.

Default: false
show_crn
bool
If show_crn is true, group CRN will be included in the response.

Default: false

Example request

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

Example request

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

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

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

Example request

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

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

System.out.println(GsonSingleton.getGson().toJson(allResults));
Copy to clipboard

Example request

const params = {
  accountId: testAccountId,
};

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

Example request

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

print(json.dumps(all_results, indent=2))
Copy to clipboard

Response

Response Body

GroupsList

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

GroupsList

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

GroupsList

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

GroupsList

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

GroupsList

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

Status Code

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

Example responses

Status 200

{
  "limit": 5,
  "offset": 0,
  "total_count": 20,
  "first": {
    "href": "https://iam.cloud.ibm.com/v2/groups?limit=5&account_id=c56eec94cb5793b8da0eb7790759aaf0&show_federated=true"
  },
  "next": {
    "href": "https://iam.cloud.ibm.com/v2/groups?offset=5&limit=5&account_id=c56eec94cb5793b8da0eb7790759aaf0&show_federated=true"
  },
  "last": {
    "href": "https://iam.cloud.ibm.com/v2/groups?offset=15&limit=5&account_id=c56eec94cb5793b8da0eb7790759aaf0&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": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-PublicAccess",
      "is_federated": false
    },
    {
      "id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
      "name": "Group 1",
      "description": "Group description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
      "is_federated": true
    },
    {
      "id": "AccessGroupId-9c6dd943-f12e-49ed-8235-5064e6aa1bf1",
      "name": "Group 2",
      "description": "Group description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-9c6dd943-f12e-49ed-8235-5064e6aa1bf1",
      "is_federated": true
    },
    {
      "id": "AccessGroupId-f1d04900-0afd-4989-bb8d-4b58cf454f42",
      "name": "Group 3",
      "description": "Group description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f1d04900-0afd-4989-bb8d-4b58cf454f42",
      "is_federated": false
    },
    {
      "id": "AccessGroupId-e3051dc7-fd2a-49d5-bad7-cc7c3f815993",
      "name": "Group 4",
      "description": "Group description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-e3051dc7-fd2a-49d5-bad7-cc7c3f815993",
      "is_federated": false
    },
    {
      "id": "AccessGroupId-3a8bd26a-c7cf-4756-90ba-85f185406bdb",
      "name": "Group 5",
      "description": "Group description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-3a8bd26a-c7cf-4756-90ba-85f185406bdb",
      "is_federated": false
    }
  ]
}
Copy to clipboard

Success example

{
  "limit": 5,
  "offset": 0,
  "total_count": 20,
  "first": {
    "href": "https://iam.cloud.ibm.com/v2/groups?limit=5&account_id=c56eec94cb5793b8da0eb7790759aaf0&show_federated=true"
  },
  "next": {
    "href": "https://iam.cloud.ibm.com/v2/groups?offset=5&limit=5&account_id=c56eec94cb5793b8da0eb7790759aaf0&show_federated=true"
  },
  "last": {
    "href": "https://iam.cloud.ibm.com/v2/groups?offset=15&limit=5&account_id=c56eec94cb5793b8da0eb7790759aaf0&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": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-PublicAccess",
      "is_federated": false
    },
    {
      "id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
      "name": "Group 1",
      "description": "Group description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
      "is_federated": true
    },
    {
      "id": "AccessGroupId-9c6dd943-f12e-49ed-8235-5064e6aa1bf1",
      "name": "Group 2",
      "description": "Group description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-9c6dd943-f12e-49ed-8235-5064e6aa1bf1",
      "is_federated": true
    },
    {
      "id": "AccessGroupId-f1d04900-0afd-4989-bb8d-4b58cf454f42",
      "name": "Group 3",
      "description": "Group description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f1d04900-0afd-4989-bb8d-4b58cf454f42",
      "is_federated": false
    },
    {
      "id": "AccessGroupId-e3051dc7-fd2a-49d5-bad7-cc7c3f815993",
      "name": "Group 4",
      "description": "Group description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-e3051dc7-fd2a-49d5-bad7-cc7c3f815993",
      "is_federated": false
    },
    {
      "id": "AccessGroupId-3a8bd26a-c7cf-4756-90ba-85f185406bdb",
      "name": "Group 5",
      "description": "Group description",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-3a8bd26a-c7cf-4756-90ba-85f185406bdb",
      "is_federated": false
    }
  ]
}
Copy to clipboard

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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)
Copy to clipboard

getAccessGroup(params)

get_access_group(
        self,
        access_group_id: str,
        *,
        transaction_id: Optional[str] = None,
        show_federated: Optional[bool] = None,
        show_crn: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-groups.groups.read

Auditing

Calling this method generates the following auditing event.

iam-groups.group.read

Request

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

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

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Query Parameters

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

Default: false
show_crn
boolean
If show_crn is true, group CRN will be included in the response.

Default: false

parameter

WithContext method only

GetAccessGroupOptions

The GetAccessGroup options.

GetAccessGroupOptions

The getAccessGroup options.

parameters

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

Default: false
showCrn
boolean
If show_crn is true, group CRN will be included in the response.

Default: false

parameters

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

Default: false
show_crn
bool
If show_crn is true, group CRN will be included in the response.

Default: false

Example request

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

Example request

getAccessGroupOptions := iamAccessGroupsService.NewGetAccessGroupOptions(
  accessGroupIDLink,
)

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

Example request

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

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

System.out.println(group);

Example request

const params = {
  accessGroupId: testGroupId,
};

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

Example request

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

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

Response

Response Body

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Status Code

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

Example responses

Status 200

{
  "id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "name": "Awesome Developers",
  "description": "Group for awesome developers",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS",
  "is_federated": true
}
Copy to clipboard

Success example

{
  "id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "name": "Awesome Developers",
  "description": "Group for awesome developers",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS",
  "is_federated": true
}
Copy to clipboard

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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)
Copy to clipboard

updateAccessGroup(params)

update_access_group(
        self,
        access_group_id: str,
        if_match: str,
        *,
        name: Optional[str] = None,
        description: Optional[str] = None,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-groups.groups.update

Auditing

Calling this method generates the following auditing event.

iam-groups.group.update

Request

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

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

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Request Body

Required*

UpdateGroupRequest

The access group to update.

Examples:

parameter

WithContext method only

UpdateAccessGroupOptions

The UpdateAccessGroup options.

UpdateAccessGroupOptions

The updateAccessGroup options.

parameters

accessGroupId
Required*
string
The access group identifier.
ifMatch
Required*
string
The current revision number of the group being updated. This can be found in the Create/Get access group response ETag header.
name
string
Give the access group a unique name that doesn't conflict with an existing access group in the account. This field is case-insensitive and has a limit of 100 characters.
Examples:
description
string
Assign an optional description for the access group. This field has a limit of 250 characters.
Examples:
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

access_group_id
Required*
str
The access group identifier.
if_match
Required*
str
The current revision number of the group being updated. This can be found in the Create/Get access group response ETag header.
name
str
Give the access group a unique name that doesn't conflict with an existing access group in the account. This field is case-insensitive and has a limit of 100 characters.
Examples:
description
str
Assign an optional description for the access group. This field has a limit of 250 characters.
Examples:
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

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

Example request

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

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

Example request

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

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

System.out.println(group);
Copy to clipboard

Example request

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

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

Example request

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

print(json.dumps(group, indent=2))
Copy to clipboard

Response

Response Body

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Group

An IAM access group.

Status Code

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

Example responses

Status 200

{
  "id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "name": "SUPER Awesome Developers",
  "description": "Group for SUPER awesome developers.",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS"
}
Copy to clipboard

Success example

{
  "id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "name": "SUPER Awesome Developers",
  "description": "Group for SUPER awesome developers.",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS"
}
Copy to clipboard

Status 400

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

Error example

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

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

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

Error example

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

Status 405

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

Error example

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

Status 409

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

Error example

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

Status 412

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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)
Copy to clipboard

deleteAccessGroup(params)

delete_access_group(
        self,
        access_group_id: str,
        *,
        transaction_id: Optional[str] = None,
        force: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-groups.groups.delete

Auditing

Calling this method generates the following auditing event.

iam-groups.group.delete

Request

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

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

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Query Parameters

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

Default: false

parameter

WithContext method only

DeleteAccessGroupOptions

The DeleteAccessGroup options.

DeleteAccessGroupOptions

The deleteAccessGroup options.

parameters

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

Default: false

parameters

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

Default: false

Example request

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

Example request

deleteAccessGroupOptions := iamAccessGroupsService.NewDeleteAccessGroupOptions(
  accessGroupIDLink,
)

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

Example request

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

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

Example request

const params = {
  accessGroupId: testGroupId,
};

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

Example request

response = iam_access_groups_service.delete_access_group(
  access_group_id=test_group_id,
)

Response

Status Code

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

Example responses

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

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

Error example

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

Status 405

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

Error example

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

Status 409

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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)
Copy to clipboard

addMembersToAccessGroup(params)

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

Authorization

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

iam-groups.members.add

Auditing

Calling this method generates the following auditing event.

iam-groups.member.add

Request

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

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

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Request Body

Required*

AddGroupMembersRequest

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

Examples:

parameter

WithContext method only

AddMembersToAccessGroupOptions

The AddMembersToAccessGroup options.

AddMembersToAccessGroupOptions

The addMembersToAccessGroup options.

parameters

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

parameters

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

Example request

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

Example request

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

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

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

Example request

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

System.out.println(addGroupMembersResponse);
Copy to clipboard

Example request

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

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

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

Example request

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

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

print(json.dumps(add_group_members_response, indent=2))
Copy to clipboard

Response

Response Body

AddGroupMembersResponse

The members added to an access group.

AddGroupMembersResponse

The members added to an access group.

AddGroupMembersResponse

The members added to an access group.

AddGroupMembersResponse

The members added to an access group.

AddGroupMembersResponse

The members added to an access group.

Status Code

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

Example responses

Status 207

{
  "members": [
    {
      "iam_id": "IBMid-06000260JS",
      "type": "user",
      "created_at": "2022-01-28T13:34:36Z",
      "created_by_id": "IBMid-06000260JS",
      "status_code": 200
    },
    {
      "iam_id": "iam-ServiceId-d5bae925-f73b-4142-8d84-a1fa3e0c7ed5",
      "status_code": 400,
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "The service id is missing or incorrect"
        }
      ]
    },
    {
      "iam_id": "iam-Profile-fcb31839-9ece-4837-b5e8-c2850a35e1fa",
      "type": "profile",
      "created_at": "2022-01-28T13:34:36Z",
      "created_by_id": "IBMid-06000260JS",
      "status_code": 200
    }
  ]
}
Copy to clipboard

Success example

{
  "members": [
    {
      "iam_id": "IBMid-06000260JS",
      "type": "user",
      "created_at": "2022-01-28T13:34:36Z",
      "created_by_id": "IBMid-06000260JS",
      "status_code": 200
    },
    {
      "iam_id": "iam-ServiceId-d5bae925-f73b-4142-8d84-a1fa3e0c7ed5",
      "status_code": 400,
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "The service id is missing or incorrect"
        }
      ]
    },
    {
      "iam_id": "iam-Profile-fcb31839-9ece-4837-b5e8-c2850a35e1fa",
      "type": "profile",
      "created_at": "2022-01-28T13:34:36Z",
      "created_by_id": "IBMid-06000260JS",
      "status_code": 200
    }
  ]
}
Copy to clipboard

Status 400

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

Error example

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

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

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

Error example

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

Status 405

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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)
Copy to clipboard

listAccessGroupMembers(params)

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

Authorization

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

iam-groups.members.list

Auditing

Calling this method generates the following auditing event.

iam-groups.members.list

Request

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

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

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Query Parameters

membership_type
string
Filters members by membership type. Filter by static, dynamic or all. static lists the members explicitly added to the access group, and dynamic lists the members that are part of the access group at that time via dynamic rules. all lists both static and dynamic members.

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

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

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

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

parameter

WithContext method only

ListAccessGroupMembersOptions

The ListAccessGroupMembers options.

ListAccessGroupMembersOptions

The listAccessGroupMembers options.

parameters

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

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

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

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

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

parameters

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

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

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

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

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

Example request

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

Example request

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

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

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

Example request

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

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

System.out.println(GsonSingleton.getGson().toJson(allResults));
Copy to clipboard

Example request

const params = {
  accessGroupId: testGroupId,
};

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

Example request

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

print(json.dumps(all_results, indent=2))
Copy to clipboard

Response

Response Body

GroupMembersList

The members of a group.

GroupMembersList

The members of a group.

GroupMembersList

The members of a group.

GroupMembersList

The members of a group.

GroupMembersList

The members of a group.

Status Code

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

Example responses

Status 200

{
  "limit": 50,
  "offset": 0,
  "total_count": 2,
  "first": {
    "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members?limit=50&verbose=true&membership_type=all"
  },
  "last": {
    "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members?offset=0&limit=50&verbose=true&membership_type=all"
  },
  "members": [
    {
      "iam_id": "IBMid-06000260JS",
      "type": "user",
      "membership_type": "static",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members/IBMid-06000260JS",
      "name": "John Doe",
      "email": "john.doe@ibm.com",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS"
    },
    {
      "iam_id": "IBMid-06000260JT",
      "type": "user",
      "membership_type": "dynamic",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members/IBMid-06000260JT",
      "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": "IBMid-06000260JS"
    },
    {
      "iam_id": "iam-ServiceId-d5bae925-f73b-4142-8d84-a1fa3e0c7ed5",
      "type": "service",
      "membership_type": "static",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members/iam-ServiceId-d5bae925-f73b-4142-8d84-a1fa3e0c7ed5",
      "name": "Service ID 1",
      "description": "This is the description of the service id.",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS"
    },
    {
      "iam_id": "iam-Profile-fcb31839-9ece-4837-b5e8-c2850a35e1fa",
      "type": "profile",
      "membership_type": "static",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members/iam-Profile-fcb31839-9ece-4837-b5e8-c2850a35e1fa",
      "name": "Trusted Profile 1",
      "description": "This is the description of the trusted profile.",
      "created_at": "2022-01-27T09:18:52Z",
      "created_by_id": "IBMid-06000260JS"
    }
  ]
}
Copy to clipboard

Success example

{
  "limit": 50,
  "offset": 0,
  "total_count": 2,
  "first": {
    "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members?limit=50&verbose=true&membership_type=all"
  },
  "last": {
    "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members?offset=0&limit=50&verbose=true&membership_type=all"
  },
  "members": [
    {
      "iam_id": "IBMid-06000260JS",
      "type": "user",
      "membership_type": "static",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members/IBMid-06000260JS",
      "name": "John Doe",
      "email": "john.doe@ibm.com",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS"
    },
    {
      "iam_id": "IBMid-06000260JT",
      "type": "user",
      "membership_type": "dynamic",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members/IBMid-06000260JT",
      "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": "IBMid-06000260JS"
    },
    {
      "iam_id": "iam-ServiceId-d5bae925-f73b-4142-8d84-a1fa3e0c7ed5",
      "type": "service",
      "membership_type": "static",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members/iam-ServiceId-d5bae925-f73b-4142-8d84-a1fa3e0c7ed5",
      "name": "Service ID 1",
      "description": "This is the description of the service id.",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS"
    },
    {
      "iam_id": "iam-Profile-fcb31839-9ece-4837-b5e8-c2850a35e1fa",
      "type": "profile",
      "membership_type": "static",
      "href": "https://iam.cloud.ibm.com/v2/groups/AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2/members/iam-Profile-fcb31839-9ece-4837-b5e8-c2850a35e1fa",
      "name": "Trusted Profile 1",
      "description": "This is the description of the trusted profile.",
      "created_at": "2022-01-27T09:18:52Z",
      "created_by_id": "IBMid-06000260JS"
    }
  ]
}
Copy to clipboard

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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)
Copy to clipboard

isMemberOfAccessGroup(params)

is_member_of_access_group(
        self,
        access_group_id: str,
        iam_id: str,
        *,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-groups.members.read

Auditing

Calling this method generates the following auditing event.

iam-groups.member.read

Request

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

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

Custom Headers

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

Path Parameters

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

parameter

WithContext method only

IsMemberOfAccessGroupOptions

The IsMemberOfAccessGroup options.

IsMemberOfAccessGroupOptions

The isMemberOfAccessGroup options.

parameters

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

parameters

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

Example request

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

Example request

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

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

Example request

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

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

Example request

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

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

Example request

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

Response

Status Code

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

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

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

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

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

ServiceCall<Void> removeMemberFromAccessGroup(RemoveMemberFromAccessGroupOptions removeMemberFromAccessGroupOptions)
Copy to clipboard

removeMemberFromAccessGroup(params)

remove_member_from_access_group(
        self,
        access_group_id: str,
        iam_id: str,
        *,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-groups.members.delete

Auditing

Calling this method generates the following auditing event.

iam-groups.member.delete

Request

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

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

Custom Headers

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

Path Parameters

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

parameter

WithContext method only

RemoveMemberFromAccessGroupOptions

The RemoveMemberFromAccessGroup options.

RemoveMemberFromAccessGroupOptions

The removeMemberFromAccessGroup options.

parameters

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

parameters

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

Example request

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

Example request

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

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


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

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


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

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

Example request

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

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

Example request

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

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

Example request

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

Response

Status Code

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

Example responses

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

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

Error example

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

Status 405

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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)
Copy to clipboard

removeMembersFromAccessGroup(params)

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

Authorization

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

iam-groups.members.delete

Auditing

Calling this method generates the following auditing event.

iam-groups.member.delete

Request

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

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

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Request Body

Required*

DeleteGroupBulkMembersRequest

The members to remove from an access group.

Examples:

parameter

WithContext method only

RemoveMembersFromAccessGroupOptions

The RemoveMembersFromAccessGroup options.

RemoveMembersFromAccessGroupOptions

The removeMembersFromAccessGroup options.

parameters

accessGroupId
Required*
string
The access group identifier.
members
string[]
The iam_ids to remove from the access group. This field has a limit of 50 iam_ids.
Examples:
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

access_group_id
Required*
str
The access group identifier.
members
List[str]
The iam_ids to remove from the access group. This field has a limit of 50 iam_ids.
Examples:
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

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

Example request

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

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

System.out.println(deleteGroupBulkMembersResponse);


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

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

System.out.println(deleteGroupBulkMembersResponse);
Copy to clipboard

Example request

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

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


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

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

Example request

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

print(json.dumps(delete_group_bulk_members_response, indent=2))
Copy to clipboard

Response

Response Body

DeleteGroupBulkMembersResponse

The access group id and the members removed from it.

DeleteGroupBulkMembersResponse

The access group id and the members removed from it.

DeleteGroupBulkMembersResponse

The access group id and the members removed from it.

DeleteGroupBulkMembersResponse

The access group id and the members removed from it.

DeleteGroupBulkMembersResponse

The access group id and the members removed from it.

Status Code

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

Example responses

Status 207

{
  "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "members": [
    {
      "iam_id": "IBMid-06000260JS",
      "status_code": 204
    },
    {
      "iam_id": "iam-ServiceId-d5bae925-f73b-4142-8d84-a1fa3e0c7ed5",
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Failed to find the membership"
        }
      ],
      "status_code": 404
    }
  ]
}
Copy to clipboard

Success example

{
  "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "members": [
    {
      "iam_id": "IBMid-06000260JS",
      "status_code": 204
    },
    {
      "iam_id": "iam-ServiceId-d5bae925-f73b-4142-8d84-a1fa3e0c7ed5",
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Failed to find the membership"
        }
      ],
      "status_code": 404
    }
  ]
}
Copy to clipboard

Status 400

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

Error example

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

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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)
Copy to clipboard

removeMemberFromAllAccessGroups(params)

remove_member_from_all_access_groups(
        self,
        account_id: str,
        iam_id: str,
        *,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-groups.members.delete

Auditing

Calling this method generates the following auditing event.

iam-groups.member.delete

Request

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

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

Custom Headers

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

Path Parameters

iam_id
Required*
string
The IAM identifier.

Query Parameters

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

parameter

WithContext method only

RemoveMemberFromAllAccessGroupsOptions

The RemoveMemberFromAllAccessGroups options.

RemoveMemberFromAllAccessGroupsOptions

The removeMemberFromAllAccessGroups options.

parameters

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

parameters

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

Example request

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

Example request

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

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

Example request

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

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

System.out.println(deleteFromAllGroupsResponse);

Example request

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

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

Example request

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

print(json.dumps(delete_from_all_groups_response, indent=2))
Copy to clipboard

Response

Response Body

DeleteFromAllGroupsResponse

The response from the delete member from access groups request.

DeleteFromAllGroupsResponse

The response from the delete member from access groups request.

DeleteFromAllGroupsResponse

The response from the delete member from access groups request.

DeleteFromAllGroupsResponse

The response from the delete member from access groups request.

DeleteFromAllGroupsResponse

The response from the delete member from access groups request.

Status Code

207
There is a multiple status response. Please check the response body.
401
Invalid Access Token.
403
Access Denied.
404
Not Found.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 207

{
  "iam_id": "some-member-id1",
  "groups": [
    {
      "access_group_id": "AccessGroupId-4e415880-3159-4f2b-b2c3-32a53ddcbd61",
      "status_code": 204
    },
    {
      "access_group_id": "AccessGroupId-b0d32f56-f85c-4bf1-af37-7bbd92b1b2b3",
      "status_code": 409,
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Cloudant document update conflict occurred"
        }
      ]
    }
  ]
}
Copy to clipboard

Success example

{
  "iam_id": "some-member-id1",
  "groups": [
    {
      "access_group_id": "AccessGroupId-4e415880-3159-4f2b-b2c3-32a53ddcbd61",
      "status_code": 204
    },
    {
      "access_group_id": "AccessGroupId-b0d32f56-f85c-4bf1-af37-7bbd92b1b2b3",
      "status_code": 409,
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Cloudant document update conflict occurred"
        }
      ]
    }
  ]
}
Copy to clipboard

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "no_groups_found",
      "message": "No groups found for member: <id>"
    }
  ],
  "status_code": 404
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "no_groups_found",
      "message": "No groups found for member: <id>"
    }
  ],
  "status_code": 404
}
Copy to clipboard

Status 500

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

Error example

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

Status 503

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

Error example

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

This API will add a member to multiple access groups in an account. The limit of how many groups that can be in the request is 50. The response is a list of results that show if adding the member to each group was successful or not.

PUT /v2/groups/_allgroups/members/{iam_id}

(iamAccessGroups *IamAccessGroupsV2) AddMemberToMultipleAccessGroups(addMemberToMultipleAccessGroupsOptions *AddMemberToMultipleAccessGroupsOptions) (result *AddMembershipMultipleGroupsResponse, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) AddMemberToMultipleAccessGroupsWithContext(ctx context.Context, addMemberToMultipleAccessGroupsOptions *AddMemberToMultipleAccessGroupsOptions) (result *AddMembershipMultipleGroupsResponse, response *core.DetailedResponse, err error)

ServiceCall<AddMembershipMultipleGroupsResponse> addMemberToMultipleAccessGroups(AddMemberToMultipleAccessGroupsOptions addMemberToMultipleAccessGroupsOptions)
Copy to clipboard

addMemberToMultipleAccessGroups(params)

add_member_to_multiple_access_groups(
        self,
        account_id: str,
        iam_id: str,
        *,
        type: Optional[str] = None,
        groups: Optional[List[str]] = None,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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 AddMemberToMultipleAccessGroupsOptions struct and set the fields to provide parameter values for the AddMemberToMultipleAccessGroups method.

Use the AddMemberToMultipleAccessGroupsOptions.Builder to create a AddMemberToMultipleAccessGroupsOptions object that contains the parameter values for the addMemberToMultipleAccessGroups method.

Custom Headers

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

Path Parameters

iam_id
Required*
string
The IAM identifier.

Query Parameters

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

Request Body

Required*

AddMembershipMultipleGroupsRequest

List of groups in the account the member should be added to.

Examples:

parameter

WithContext method only

AddMemberToMultipleAccessGroupsOptions

The AddMemberToMultipleAccessGroups options.

AddMemberToMultipleAccessGroupsOptions

The addMemberToMultipleAccessGroups options.

parameters

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

parameters

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

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "type": "user", "groups": [ "AccessGroupId-b0d32f56-f85c-4bf1-af37-7bbd92b1b2b3" ] }'   "{base_url}/v2/groups/_allgroups/members/{iam_id}?account_id={account_id}"
Copy to clipboard

Example request

addMemberToMultipleAccessGroupsOptions := iamAccessGroupsService.NewAddMemberToMultipleAccessGroupsOptions(
  testAccountID,
  "IBMid-user1",
)

addMemberToMultipleAccessGroupsOptions.SetType("user")
addMemberToMultipleAccessGroupsOptions.SetGroups([]string{accessGroupIDLink})

addMembershipMultipleGroupsResponse, response, err := iamAccessGroupsService.AddMemberToMultipleAccessGroups(addMemberToMultipleAccessGroupsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(addMembershipMultipleGroupsResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

AddMemberToMultipleAccessGroupsOptions addMemberToMultipleAccessGroupsOptions = new AddMemberToMultipleAccessGroupsOptions.Builder()
  .accountId(testAccountId)
  .iamId("IBMid-user1")
  .type("user")
  .addGroups(testGroupId)
  .build();

Response<AddMembershipMultipleGroupsResponse> response = iamAccessGroupsService.addMemberToMultipleAccessGroups(addMemberToMultipleAccessGroupsOptions).execute();
AddMembershipMultipleGroupsResponse addMembershipMultipleGroupsResponse = response.getResult();

System.out.println(addMembershipMultipleGroupsResponse);
Copy to clipboard

Example request

const params = {
  accountId: testAccountId,
  iamId: 'IBMid-user1',
  type: 'user',
  groups: [testGroupId]
};

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

Example request

response = iam_access_groups_service.add_member_to_multiple_access_groups(
  account_id=test_account_id,
  iam_id='IBMid-user1',
  type='user',
  groups=[test_group_id],
)
add_membership_multiple_groups_response = response.get_result()

print(json.dumps(add_membership_multiple_groups_response, indent=2))
Copy to clipboard

Response

Response Body

AddMembershipMultipleGroupsResponse

The response from the add member to multiple access groups request.

AddMembershipMultipleGroupsResponse

The response from the add member to multiple access groups request.

AddMembershipMultipleGroupsResponse

The response from the add member to multiple access groups request.

AddMembershipMultipleGroupsResponse

The response from the add member to multiple access groups request.

AddMembershipMultipleGroupsResponse

The response from the add member to multiple access groups request.

Status Code

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

Example responses

Status 207

{
  "groups": [
    {
      "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
      "status_code": 200
    },
    {
      "access_group_id": "AccessGroupId-9c6dd943-f12e-49ed-8235-5064e6aa1bf1",
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Group not found in account"
        }
      ],
      "status_code": 404
    },
    {
      "access_group_id": "AccessGroupId-f1d04900-0afd-4989-bb8d-4b58cf454f42",
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ac",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  ]
}
Copy to clipboard

Success example

{
  "groups": [
    {
      "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
      "status_code": 200
    },
    {
      "access_group_id": "AccessGroupId-9c6dd943-f12e-49ed-8235-5064e6aa1bf1",
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Group not found in account"
        }
      ],
      "status_code": 404
    },
    {
      "access_group_id": "AccessGroupId-f1d04900-0afd-4989-bb8d-4b58cf454f42",
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ac",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  ]
}
Copy to clipboard

Status 400

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "duplicate_groupid_error",
      "message": "A duplicate groupId entry was found for AccessGroupId-f1d04900-0afd-4989-bb8d-4b58cf454f42. Please remove any duplicate entries."
    }
  ],
  "status_code": 400
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "duplicate_groupid_error",
      "message": "A duplicate groupId entry was found for AccessGroupId-f1d04900-0afd-4989-bb8d-4b58cf454f42. Please remove any duplicate entries."
    }
  ],
  "status_code": 400
}
Copy to clipboard

Status 401

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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

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

POST /v2/groups/{access_group_id}/rules

(iamAccessGroups *IamAccessGroupsV2) AddAccessGroupRule(addAccessGroupRuleOptions *AddAccessGroupRuleOptions) (result *Rule, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) AddAccessGroupRuleWithContext(ctx context.Context, addAccessGroupRuleOptions *AddAccessGroupRuleOptions) (result *Rule, response *core.DetailedResponse, err error)

ServiceCall<Rule> addAccessGroupRule(AddAccessGroupRuleOptions addAccessGroupRuleOptions)
Copy to clipboard

addAccessGroupRule(params)

add_access_group_rule(
        self,
        access_group_id: str,
        expiration: int,
        realm_name: str,
        conditions: List['RuleConditions'],
        *,
        name: Optional[str] = None,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.rules.create

Auditing

Calling this method generates the following auditing event.

iam-groups.rule.create

Request

Instantiate the AddAccessGroupRuleOptions struct and set the fields to provide parameter values for the AddAccessGroupRule method.

Use the AddAccessGroupRuleOptions.Builder to create a AddAccessGroupRuleOptions object that contains the parameter values for the addAccessGroupRule method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

Request Body

Required*

RuleRequest

A new dynamic rule to add to an access group.

Examples:

parameter

WithContext method only

AddAccessGroupRuleOptions

The AddAccessGroupRule options.

AddAccessGroupRuleOptions

The addAccessGroupRule options.

parameters

accessGroupId
Required*
string
The access group identifier.
expiration
Required*
number
Session duration in hours. Access group membership is revoked after this time period expires. Users must log back in to refresh their access group membership.

Possible values: 1 ≤ value ≤ 24
Examples:
realmName
Required*
string
The URL of the identity provider (IdP).
Examples:
conditions
Required*
A list of conditions that identities must satisfy to gain access group membership.
Examples:
name
string
The name of the dynaimic rule.
Examples:
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

access_group_id
Required*
str
The access group identifier.
expiration
Required*
int
Session duration in hours. Access group membership is revoked after this time period expires. Users must log back in to refresh their access group membership.

Possible values: 1 ≤ value ≤ 24
Examples:
realm_name
Required*
str
The URL of the identity provider (IdP).
Examples:
conditions
Required*
A list of conditions that identities must satisfy to gain access group membership.
Examples:
name
str
The name of the dynaimic rule.
Examples:
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "name": "Manager group rule", "expiration": 12, "realm_name": "https://idp.example.org/SAML2", "conditions": [ { "claim": "isManager", "operator": "EQUALS", "value": "true" } ] }'   "{base_url}/v2/groups/{access_group_id}/rules"
Copy to clipboard

Example request

ruleConditionsModel := &iamaccessgroupsv2.RuleConditions{
  Claim:    core.StringPtr("isManager"),
  Operator: core.StringPtr("EQUALS"),
  Value:    core.StringPtr("true"),
}

addAccessGroupRuleOptions := iamAccessGroupsService.NewAddAccessGroupRuleOptions(
  accessGroupIDLink,
  int64(12),
  "https://idp.example.org/SAML2a",
  []iamaccessgroupsv2.RuleConditions{*ruleConditionsModel},
)
addAccessGroupRuleOptions.SetName("Manager group rule")

rule, response, err := iamAccessGroupsService.AddAccessGroupRule(addAccessGroupRuleOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(rule, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

RuleConditions ruleConditionsModel = new RuleConditions.Builder()
  .claim("isManager")
  .operator("EQUALS")
  .value("true")
  .build();
AddAccessGroupRuleOptions addAccessGroupRuleOptions = new AddAccessGroupRuleOptions.Builder()
  .accessGroupId(testGroupId)
  .name("Manager group rule")
  .expiration(12)
  .realmName("https://idp.example.org/SAML2a")
  .addConditions(ruleConditionsModel)
  .build();

Response<Rule> response = iamAccessGroupsService.addAccessGroupRule(addAccessGroupRuleOptions).execute();
Rule rule = response.getResult();

System.out.println(rule);
Copy to clipboard

Example request

const params = {
  accessGroupId: testGroupId,
  name: 'Manager group rule',
  expiration: 12,
  realmName: 'https://idp.example.org/SAML2a',
  conditions: [
    {
      claim: 'isManager',
      operator: 'EQUALS',
      value: 'true',
    },
  ],
};

try {
  const res = await iamAccessGroupsService.addAccessGroupRule(params);
  testClaimRuleId = res.result.id;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

rule_conditions_model = {
  'claim': 'isManager',
  'operator': 'EQUALS',
  'value': 'true',
}

response = iam_access_groups_service.add_access_group_rule(
  access_group_id=test_group_id,
  expiration=12,
  realm_name='https://idp.example.org/SAML3',
  conditions=[rule_conditions_model],
  name='Manager group rule',
)
rule = response.get_result()
Copy to clipboard

Response

Response Body

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Status Code

201
Rule Created.
400
Bad Request.
401
Invalid Access Token.
403
Access Denied.
404
Not Found.
405
Method Not Allowed.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 201

{
  "id": "ClaimRule-1396773d-366b-487d-b44e-be92238e2bb3",
  "name": "test rule name",
  "expiration": 24,
  "realm_name": "test-idp.com",
  "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "conditions": [
    {
      "claim": "cn",
      "operator": "EQUALS",
      "value": "\"Some Name\""
    }
  ],
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS"
}
Copy to clipboard

Success example

{
  "id": "ClaimRule-1396773d-366b-487d-b44e-be92238e2bb3",
  "name": "test rule name",
  "expiration": 24,
  "realm_name": "test-idp.com",
  "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "conditions": [
    {
      "claim": "cn",
      "operator": "EQUALS",
      "value": "\"Some Name\""
    }
  ],
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS"
}
Copy to clipboard

Status 400

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "BXNIM0109E",
      "message": "Property missing or empty"
    }
  ],
  "status_code": 400
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "BXNIM0109E",
      "message": "Property missing or empty"
    }
  ],
  "status_code": 400
}
Copy to clipboard

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

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

Error example

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

Status 405

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot create rule for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot create rule for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}
Copy to clipboard

Status 500

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

Error example

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

Status 503

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

Error example

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

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

GET /v2/groups/{access_group_id}/rules

(iamAccessGroups *IamAccessGroupsV2) ListAccessGroupRules(listAccessGroupRulesOptions *ListAccessGroupRulesOptions) (result *RulesList, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) ListAccessGroupRulesWithContext(ctx context.Context, listAccessGroupRulesOptions *ListAccessGroupRulesOptions) (result *RulesList, response *core.DetailedResponse, err error)

ServiceCall<RulesList> listAccessGroupRules(ListAccessGroupRulesOptions listAccessGroupRulesOptions)
Copy to clipboard

listAccessGroupRules(params)

list_access_group_rules(
        self,
        access_group_id: str,
        *,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.rules.list

Auditing

Calling this method generates the following auditing event.

iam-groups.rules.list

Request

Instantiate the ListAccessGroupRulesOptions struct and set the fields to provide parameter values for the ListAccessGroupRules method.

Use the ListAccessGroupRulesOptions.Builder to create a ListAccessGroupRulesOptions object that contains the parameter values for the listAccessGroupRules method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.

parameter

WithContext method only

ListAccessGroupRulesOptions

The ListAccessGroupRules options.

ListAccessGroupRulesOptions

The listAccessGroupRules options.

parameters

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

parameters

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

Example request

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

Example request

listAccessGroupRulesOptions := iamAccessGroupsService.NewListAccessGroupRulesOptions(
  accessGroupIDLink,
)

rulesList, response, err := iamAccessGroupsService.ListAccessGroupRules(listAccessGroupRulesOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(rulesList, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListAccessGroupRulesOptions listAccessGroupRulesOptions = new ListAccessGroupRulesOptions.Builder()
  .accessGroupId(testGroupId)
  .build();

Response<RulesList> response = iamAccessGroupsService.listAccessGroupRules(listAccessGroupRulesOptions).execute();
RulesList rulesList = response.getResult();

System.out.println(rulesList);

Example request

const params = {
  accessGroupId: testGroupId,
};

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

Example request

response = iam_access_groups_service.list_access_group_rules(
  access_group_id=test_group_id,
)
rules_list = response.get_result()

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

Response

Response Body

RulesList

A list of dynamic rules attached to the access group.

RulesList

A list of dynamic rules attached to the access group.

RulesList

A list of dynamic rules attached to the access group.

RulesList

A list of dynamic rules attached to the access group.

RulesList

A list of dynamic rules attached to the access group.

Status Code

200
List all rules in the given access group.
401
Invalid Access Token.
403
Access Denied.
404
Not Found.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 200

{
  "rules": [
    {
      "id": "ClaimRule-ad9aac71-49bc-457c-9588-23b60e442d23",
      "name": "test rule name",
      "expiration": 24,
      "realm_name": "test-idp.com",
      "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
      "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
      "conditions": [
        {
          "claim": "blueGroups",
          "operator": "CONTAINS",
          "value": "\"test-bluegroup-saml\""
        }
      ],
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS"
    },
    {
      "id": "ClaimRule-8e8e3255-c928-47d1-85e7-195b5d6a0e55",
      "name": "test rule name 2",
      "expiration": 24,
      "realm_name": "test-idp.com",
      "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
      "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
      "conditions": [
        {
          "claim": "blueGroups",
          "operator": "CONTAINS",
          "value": "\"test-bluegroup-saml2\""
        }
      ],
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS"
    }
  ]
}
Copy to clipboard

Success example

{
  "rules": [
    {
      "id": "ClaimRule-ad9aac71-49bc-457c-9588-23b60e442d23",
      "name": "test rule name",
      "expiration": 24,
      "realm_name": "test-idp.com",
      "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
      "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
      "conditions": [
        {
          "claim": "blueGroups",
          "operator": "CONTAINS",
          "value": "\"test-bluegroup-saml\""
        }
      ],
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS"
    },
    {
      "id": "ClaimRule-8e8e3255-c928-47d1-85e7-195b5d6a0e55",
      "name": "test rule name 2",
      "expiration": 24,
      "realm_name": "test-idp.com",
      "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
      "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
      "conditions": [
        {
          "claim": "blueGroups",
          "operator": "CONTAINS",
          "value": "\"test-bluegroup-saml2\""
        }
      ],
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "IBMid-06000260JS",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "IBMid-06000260JS"
    }
  ]
}
Copy to clipboard

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

Retrieve a rule from an access group. A revision number is returned in the ETag header, which is needed when updating the rule.

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

(iamAccessGroups *IamAccessGroupsV2) GetAccessGroupRule(getAccessGroupRuleOptions *GetAccessGroupRuleOptions) (result *Rule, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) GetAccessGroupRuleWithContext(ctx context.Context, getAccessGroupRuleOptions *GetAccessGroupRuleOptions) (result *Rule, response *core.DetailedResponse, err error)

ServiceCall<Rule> getAccessGroupRule(GetAccessGroupRuleOptions getAccessGroupRuleOptions)
Copy to clipboard

getAccessGroupRule(params)

get_access_group_rule(
        self,
        access_group_id: str,
        rule_id: str,
        *,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.rules.read

Auditing

Calling this method generates the following auditing event.

iam-groups.rule.read

Request

Instantiate the GetAccessGroupRuleOptions struct and set the fields to provide parameter values for the GetAccessGroupRule method.

Use the GetAccessGroupRuleOptions.Builder to create a GetAccessGroupRuleOptions object that contains the parameter values for the getAccessGroupRule method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.
rule_id
Required*
string
The rule to get.

parameter

WithContext method only

GetAccessGroupRuleOptions

The GetAccessGroupRule options.

GetAccessGroupRuleOptions

The getAccessGroupRule options.

parameters

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

parameters

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

Example request

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

Example request

getAccessGroupRuleOptions := iamAccessGroupsService.NewGetAccessGroupRuleOptions(
  accessGroupIDLink,
  testClaimRuleID,
)

rule, response, err := iamAccessGroupsService.GetAccessGroupRule(getAccessGroupRuleOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(rule, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetAccessGroupRuleOptions getAccessGroupRuleOptions = new GetAccessGroupRuleOptions.Builder()
  .accessGroupId(testGroupId)
  .ruleId(testClaimRuleId)
  .build();

Response<Rule> response = iamAccessGroupsService.getAccessGroupRule(getAccessGroupRuleOptions).execute();
Rule rule = response.getResult();

System.out.println(rule);

Example request

const params = {
  accessGroupId: testGroupId,
  ruleId: testClaimRuleId,
};

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

Example request

response = iam_access_groups_service.get_access_group_rule(
  access_group_id=test_group_id,
  rule_id=test_claim_rule_id,
)
rule = response.get_result()

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

Response

Response Body

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Status Code

200
Get Rule Successful.
400
Bad Request.
401
Invalid Access Token.
403
Access Denied.
404
Rule not found.
405
Method Not Allowed.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 200

{
  "id": "ClaimRule-8e8e3255-c928-47d1-85e7-195b5d6a0e55",
  "name": "test rule name",
  "expiration": 24,
  "realm_name": "test-idp.com",
  "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "conditions": [
    {
      "claim": "blueGroups",
      "operator": "CONTAINS",
      "value": "\"test-bluegroup-saml\""
    }
  ],
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS"
}
Copy to clipboard

Success example

{
  "id": "ClaimRule-8e8e3255-c928-47d1-85e7-195b5d6a0e55",
  "name": "test rule name",
  "expiration": 24,
  "realm_name": "test-idp.com",
  "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "conditions": [
    {
      "claim": "blueGroups",
      "operator": "CONTAINS",
      "value": "\"test-bluegroup-saml\""
    }
  ],
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS"
}
Copy to clipboard

Status 400

{
  "StatusCode": 400,
  "code": "BXNIM0109E",
  "message": "Property missing or empty"
}
Copy to clipboard

Error example

{
  "StatusCode": 400,
  "code": "BXNIM0109E",
  "message": "Property missing or empty"
}
Copy to clipboard

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "BXNIM0102E",
      "message": "Object type ClaimRule with ID <id> not found"
    }
  ],
  "status_code": 404
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "BXNIM0102E",
      "message": "Object type ClaimRule with ID <id> not found"
    }
  ],
  "status_code": 404
}
Copy to clipboard

Status 405

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot get rule for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "method_not_allowed_for_group",
      "message": "Cannot get rule for: AccessGroupId-PublicAccess"
    }
  ],
  "status_code": 405
}
Copy to clipboard

Status 500

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

Error example

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

Status 503

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

Error example

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

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

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

(iamAccessGroups *IamAccessGroupsV2) ReplaceAccessGroupRule(replaceAccessGroupRuleOptions *ReplaceAccessGroupRuleOptions) (result *Rule, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) ReplaceAccessGroupRuleWithContext(ctx context.Context, replaceAccessGroupRuleOptions *ReplaceAccessGroupRuleOptions) (result *Rule, response *core.DetailedResponse, err error)

ServiceCall<Rule> replaceAccessGroupRule(ReplaceAccessGroupRuleOptions replaceAccessGroupRuleOptions)
Copy to clipboard

replaceAccessGroupRule(params)

replace_access_group_rule(
        self,
        access_group_id: str,
        rule_id: str,
        if_match: str,
        expiration: int,
        realm_name: str,
        conditions: List['RuleConditions'],
        *,
        name: Optional[str] = None,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.rules.update

Auditing

Calling this method generates the following auditing event.

iam-groups.rule.update

Request

Instantiate the ReplaceAccessGroupRuleOptions struct and set the fields to provide parameter values for the ReplaceAccessGroupRule method.

Use the ReplaceAccessGroupRuleOptions.Builder to create a ReplaceAccessGroupRuleOptions object that contains the parameter values for the replaceAccessGroupRule method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.
rule_id
Required*
string
The rule to get.

Request Body

Required*

RuleRequest

A new dynamic rule to add to an access group.

Examples:

parameter

WithContext method only

ReplaceAccessGroupRuleOptions

The ReplaceAccessGroupRule options.

ReplaceAccessGroupRuleOptions

The replaceAccessGroupRule options.

parameters

accessGroupId
Required*
string
The access group identifier.
ruleId
Required*
string
The rule to get.
ifMatch
Required*
string
The current revision number of the rule being updated. This can be found in the Get Rule response ETag header.
expiration
Required*
number
Session duration in hours. Access group membership is revoked after this time period expires. Users must log back in to refresh their access group membership.

Possible values: 1 ≤ value ≤ 24
Examples:
realmName
Required*
string
The URL of the identity provider (IdP).
Examples:
conditions
Required*
A list of conditions that identities must satisfy to gain access group membership.
Examples:
name
string
The name of the dynaimic rule.
Examples:
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

access_group_id
Required*
str
The access group identifier.
rule_id
Required*
str
The rule to get.
if_match
Required*
str
The current revision number of the rule being updated. This can be found in the Get Rule response ETag header.
expiration
Required*
int
Session duration in hours. Access group membership is revoked after this time period expires. Users must log back in to refresh their access group membership.

Possible values: 1 ≤ value ≤ 24
Examples:
realm_name
Required*
str
The URL of the identity provider (IdP).
Examples:
conditions
Required*
A list of conditions that identities must satisfy to gain access group membership.
Examples:
name
str
The name of the dynaimic rule.
Examples:
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

curl -X PUT --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "If-Match: {if_match}"   --header "Content-Type: application/json"   --data '{ "name": "Manager group rule", "expiration": 12, "realm_name": "https://idp.example.org/SAML2", "conditions": [ { "claim": "isManager", "operator": "EQUALS", "value": "true" } ] }'   "{base_url}/v2/groups/{access_group_id}/rules/{rule_id}"
Copy to clipboard

Example request

ruleConditionsModel := &iamaccessgroupsv2.RuleConditions{
  Claim:    core.StringPtr("isManager"),
  Operator: core.StringPtr("EQUALS"),
  Value:    core.StringPtr("true"),
}

replaceAccessGroupRuleOptions := iamAccessGroupsService.NewReplaceAccessGroupRuleOptions(
  accessGroupIDLink,
  testClaimRuleID,
  testClaimRuleEtag,
  int64(12),
  "https://idp.example.org/SAML2",
  []iamaccessgroupsv2.RuleConditions{*ruleConditionsModel},
)
replaceAccessGroupRuleOptions.SetName("Manager group rule")

rule, response, err := iamAccessGroupsService.ReplaceAccessGroupRule(replaceAccessGroupRuleOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(rule, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

RuleConditions ruleConditionsModel = new RuleConditions.Builder()
  .claim("isManager")
  .operator("EQUALS")
  .value("true")
  .build();
ReplaceAccessGroupRuleOptions replaceAccessGroupRuleOptions = new ReplaceAccessGroupRuleOptions.Builder()
  .accessGroupId(testGroupId)
  .ruleId(testClaimRuleId)
  .ifMatch(testClaimRuleETag)
  .name("Manager group rule")
  .expiration(24)
  .realmName("https://idp.example.org/SAML2\"")
  .addConditions(ruleConditionsModel)
  .build();

Response<Rule> response = iamAccessGroupsService.replaceAccessGroupRule(replaceAccessGroupRuleOptions).execute();
Rule rule = response.getResult();

System.out.println(rule);
Copy to clipboard

Example request

const params = {
  accessGroupId: testGroupId,
  ruleId: testClaimRuleId,
  ifMatch: testClaimRuleETag,
  name: 'Manager group rule',
  expiration: 24,
  realmName: 'https://idp.example.org/SAML2',
  conditions: [
    {
      claim: 'isManager',
      operator: 'EQUALS',
      value: 'true',
    },
  ]
};

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

Example request

rule_conditions_model = {
  'claim': 'isManager',
  'operator': 'EQUALS',
  'value': 'true',
}

response = iam_access_groups_service.replace_access_group_rule(
  access_group_id=test_group_id,
  rule_id=test_claim_rule_id,
  if_match=test_claim_rule_etag,
  expiration=12,
  realm_name='https://idp.example.org/SAML3',
  conditions=[rule_conditions_model],
  name='Manager group rule',
)
rule = response.get_result()

print(json.dumps(rule, indent=2))
Copy to clipboard

Response

Response Body

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Rule

A dynamic rule of an access group.

Status Code

200
Rule Updated.
400
Bad Request.
401
Invalid Access Token.
403
Access Denied.
404
Rule not found.
405
Method Not Allowed.
412
Precondition Failed.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 200

{
  "id": "ClaimRule-8e8e3255-c928-47d1-85e7-195b5d6a0e55",
  "name": "test rule name",
  "expiration": 1,
  "realm_name": "test-idp.com",
  "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "conditions": [
    {
      "claim": "blueGroups",
      "operator": "CONTAINS",
      "value": "\"test-bluegroup-saml\""
    }
  ],
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-06-11T13:16:00Z",
  "last_modified_by_id": "IBMid-06000260JS"
}
Copy to clipboard

Success example

{
  "id": "ClaimRule-8e8e3255-c928-47d1-85e7-195b5d6a0e55",
  "name": "test rule name",
  "expiration": 1,
  "realm_name": "test-idp.com",
  "access_group_id": "AccessGroupId-f13ac227-b856-4268-bf03-69ad24284bf2",
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "conditions": [
    {
      "claim": "blueGroups",
      "operator": "CONTAINS",
      "value": "\"test-bluegroup-saml\""
    }
  ],
  "created_at": "2019-01-01T01:01:00Z",
  "created_by_id": "IBMid-06000260JS",
  "last_modified_at": "2019-06-11T13:16:00Z",
  "last_modified_by_id": "IBMid-06000260JS"
}
Copy to clipboard

Status 400

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "BXNIM0109E",
      "message": "Property missing or empty"
    }
  ],
  "status_code": 400
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "BXNIM0109E",
      "message": "Property missing or empty"
    }
  ],
  "status_code": 400
}
Copy to clipboard

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "BXNIM0102E",
      "message": "Object type ClaimRule with ID <id> not found"
    }
  ],
  "status_code": 404
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "BXNIM0102E",
      "message": "Object type ClaimRule with ID <id> not found"
    }
  ],
  "status_code": 404
}
Copy to clipboard

Status 405

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

Error example

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

Status 412

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

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

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

(iamAccessGroups *IamAccessGroupsV2) RemoveAccessGroupRule(removeAccessGroupRuleOptions *RemoveAccessGroupRuleOptions) (response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) RemoveAccessGroupRuleWithContext(ctx context.Context, removeAccessGroupRuleOptions *RemoveAccessGroupRuleOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> removeAccessGroupRule(RemoveAccessGroupRuleOptions removeAccessGroupRuleOptions)
Copy to clipboard

removeAccessGroupRule(params)

remove_access_group_rule(
        self,
        access_group_id: str,
        rule_id: str,
        *,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.rules.delete

Auditing

Calling this method generates the following auditing event.

iam-groups.rule.delete

Request

Instantiate the RemoveAccessGroupRuleOptions struct and set the fields to provide parameter values for the RemoveAccessGroupRule method.

Use the RemoveAccessGroupRuleOptions.Builder to create a RemoveAccessGroupRuleOptions object that contains the parameter values for the removeAccessGroupRule method.

Custom Headers

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

Path Parameters

access_group_id
Required*
string
The access group identifier.
rule_id
Required*
string
The rule to get.

parameter

WithContext method only

RemoveAccessGroupRuleOptions

The RemoveAccessGroupRule options.

RemoveAccessGroupRuleOptions

The removeAccessGroupRule options.

parameters

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

parameters

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

Example request

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

Example request

removeAccessGroupRuleOptions := iamAccessGroupsService.NewRemoveAccessGroupRuleOptions(
  accessGroupIDLink,
  testClaimRuleID,
)

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

Example request

RemoveAccessGroupRuleOptions removeAccessGroupRuleOptions = new RemoveAccessGroupRuleOptions.Builder()
  .accessGroupId(testGroupId)
  .ruleId(testClaimRuleId)
  .build();

Response<Void> response = iamAccessGroupsService.removeAccessGroupRule(removeAccessGroupRuleOptions).execute();

Example request

const params = {
  accessGroupId: testGroupId,
  ruleId: testClaimRuleId,
};

try {
  await iamAccessGroupsService.removeAccessGroupRule(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_access_groups_service.remove_access_group_rule(
  access_group_id=test_group_id,
  rule_id=test_claim_rule_id,
)

Response

Status Code

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

Example responses

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 404

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "BXNIM0102E",
      "message": "Object type ClaimRule with ID <id> not found"
    }
  ],
  "status_code": 404
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "BXNIM0102E",
      "message": "Object type ClaimRule with ID <id> not found"
    }
  ],
  "status_code": 404
}
Copy to clipboard

Status 405

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

Retrieve the access groups settings for a specific account.

GET /v2/groups/settings

(iamAccessGroups *IamAccessGroupsV2) GetAccountSettings(getAccountSettingsOptions *GetAccountSettingsOptions) (result *AccountSettings, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) GetAccountSettingsWithContext(ctx context.Context, getAccountSettingsOptions *GetAccountSettingsOptions) (result *AccountSettings, response *core.DetailedResponse, err error)

ServiceCall<AccountSettings> getAccountSettings(GetAccountSettingsOptions getAccountSettingsOptions)
Copy to clipboard

getAccountSettings(params)

get_account_settings(
        self,
        account_id: str,
        *,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.account-settings.read

Auditing

Calling this method generates the following auditing event.

iam-groups.account-settings.read

Request

Instantiate the GetAccountSettingsOptions struct and set the fields to provide parameter values for the GetAccountSettings method.

Use the GetAccountSettingsOptions.Builder to create a GetAccountSettingsOptions object that contains the parameter values for the getAccountSettings method.

Custom Headers

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

Query Parameters

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

parameter

WithContext method only

GetAccountSettingsOptions

The GetAccountSettings options.

GetAccountSettingsOptions

The getAccountSettings options.

parameters

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

parameters

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

Example request

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

Example request

getAccountSettingsOptions := iamAccessGroupsService.NewGetAccountSettingsOptions(
  testAccountID,
)

accountSettings, response, err := iamAccessGroupsService.GetAccountSettings(getAccountSettingsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(accountSettings, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

      GetAccountSettingsOptions getAccountSettingsOptions = new GetAccountSettingsOptions.Builder()
          .accountId(accountID)
          .build();

      Response<AccountSettings> response = contextBasedRestrictionsService.getAccountSettings(getAccountSettingsOptions).execute();
      AccountSettings accountSettings = response.getResult();

      System.out.println(accountSettings);
GetAccountSettingsOptions getAccountSettingsOptions = new GetAccountSettingsOptions.Builder()
  .accountId(accountId)
  .build();

Response<AccountSettings> response = ibmCloudShellService.getAccountSettings(getAccountSettingsOptions).execute();
AccountSettings accountSettings = response.getResult();

System.out.println(accountSettings);

GetAccountSettingsOptions getAccountSettingsOptions = new GetAccountSettingsOptions.Builder()
  .accountId(testAccountId)
  .build();

Response<AccountSettings> response = iamAccessGroupsService.getAccountSettings(getAccountSettingsOptions).execute();
AccountSettings accountSettings = response.getResult();

System.out.println(accountSettings);
Copy to clipboard

Example request

const params = {
  accountId: testAccountId,
};

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


const params = {
  accountId: accountId,
};

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


const params = {
  accountId,
};

try {
  const res = await contextBasedRestrictionsService.getAccountSettings(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_access_groups_service.get_account_settings(
  account_id=test_account_id,
)
account_settings = response.get_result()

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


response = context_based_restrictions_service.get_account_settings(
  account_id=account_id,
)
account_settings = response.get_result()

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


account_settings = ibm_cloud_shell_service.get_account_settings(account_id=account_id).get_result()

print(json.dumps(account_settings, indent=2))
Copy to clipboard

Response

Response Body

AccountSettings

The access groups settings for a specific account.

AccountSettings

The access groups settings for a specific account.

AccountSettings

The access groups settings for a specific account.

AccountSettings

The access groups settings for a specific account.

AccountSettings

The access groups settings for a specific account.

Status Code

200
Get Successful.
400
Invalid Account ID.
401
Invalid Access Token.
403
Access Denied.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 200

{
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS",
  "public_access_enabled": true
}
Copy to clipboard

Success example

{
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS",
  "public_access_enabled": true
}
Copy to clipboard

Status 400

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_account_id",
      "message": "The account id, c56eec94cb5793b8da0eb7790759aaf0, is invalid"
    }
  ],
  "status_code": 400
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_account_id",
      "message": "The account id, c56eec94cb5793b8da0eb7790759aaf0, is invalid"
    }
  ],
  "status_code": 400
}
Copy to clipboard

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

Update the access groups settings for a specific account. Note: When the public_access_enabled setting is set to false, all policies within the account attached to the Public Access group will be deleted. Only set public_access_enabled to false if you are sure that you want those policies to be removed.

PATCH /v2/groups/settings

(iamAccessGroups *IamAccessGroupsV2) UpdateAccountSettings(updateAccountSettingsOptions *UpdateAccountSettingsOptions) (result *AccountSettings, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) UpdateAccountSettingsWithContext(ctx context.Context, updateAccountSettingsOptions *UpdateAccountSettingsOptions) (result *AccountSettings, response *core.DetailedResponse, err error)

ServiceCall<AccountSettings> updateAccountSettings(UpdateAccountSettingsOptions updateAccountSettingsOptions)
Copy to clipboard

updateAccountSettings(params)

update_account_settings(
        self,
        account_id: str,
        *,
        public_access_enabled: Optional[bool] = None,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.account-settings.update

Auditing

Calling this method generates the following auditing event.

iam-groups.account-settings.update

Request

Instantiate the UpdateAccountSettingsOptions struct and set the fields to provide parameter values for the UpdateAccountSettings method.

Use the UpdateAccountSettingsOptions.Builder to create a UpdateAccountSettingsOptions object that contains the parameter values for the updateAccountSettings method.

Custom Headers

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

Query Parameters

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

Request Body

Required*

AccountSettingsRequest

The account settings to update.

Examples:

parameter

WithContext method only

UpdateAccountSettingsOptions

The UpdateAccountSettings options.

UpdateAccountSettingsOptions

The updateAccountSettings options.

parameters

accountId
Required*
string
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
publicAccessEnabled
boolean
This flag controls the public access feature within the account. It is set to true by default. Note: When this flag is set to false, all policies within the account attached to the Public Access group will be deleted.
Examples:
transactionId
string
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

parameters

account_id
Required*
str
Account ID of the API keys(s) to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.
public_access_enabled
bool
This flag controls the public access feature within the account. It is set to true by default. Note: When this flag is set to false, all policies within the account attached to the Public Access group will be deleted.
Examples:
transaction_id
str
An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose. If no transaction ID is passed in, then a random ID is generated.

Example request

curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "public_access_enabled": true }'   "{base_url}/v2/groups/settings?account_id={account_id}"
Copy to clipboard

Example request

updateAccountSettingsOptions := iamAccessGroupsService.NewUpdateAccountSettingsOptions(
  testAccountID,
)
updateAccountSettingsOptions.SetPublicAccessEnabled(true)

accountSettings, response, err := iamAccessGroupsService.UpdateAccountSettings(updateAccountSettingsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(accountSettings, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

Feature fileManagerFeatureModel = new Feature.Builder()
  .enabled(false)
  .key("server.file_manager")
  .build();
Feature webPreviewFeatureModel = new Feature.Builder()
  .enabled(true)
  .key("server.web_preview")
  .build();

RegionSetting euRegionSettingModel = new RegionSetting.Builder()
  .enabled(true)
  .key("eu-de")
  .build();
RegionSetting jpRegionSettingModel = new RegionSetting.Builder()
  .enabled(false)
  .key("jp-tok")
  .build();
RegionSetting usRegionSettingModel = new RegionSetting.Builder()
  .enabled(false)
  .key("us-south")
  .build();

UpdateAccountSettingsOptions updateAccountSettingsOptions = new UpdateAccountSettingsOptions.Builder()
  .accountId(accountId)
  .rev(String.format("130-%s", accountId))
  .defaultEnableNewFeatures(false)
  .defaultEnableNewRegions(true)
  .enabled(true)
  .features(new java.util.ArrayList<Feature>(java.util.Arrays.asList(fileManagerFeatureModel, webPreviewFeatureModel)))
  .regions(new java.util.ArrayList<RegionSetting>(java.util.Arrays.asList(euRegionSettingModel, jpRegionSettingModel, usRegionSettingModel)))
  .build();

Response<AccountSettings> response = ibmCloudShellService.updateAccountSettings(updateAccountSettingsOptions).execute();
AccountSettings accountSettings = response.getResult();

System.out.println(accountSettings);

UpdateAccountSettingsOptions updateAccountSettingsOptions = new UpdateAccountSettingsOptions.Builder()
  .accountId(testAccountId)
  .publicAccessEnabled(true)
  .build();

Response<AccountSettings> response = iamAccessGroupsService.updateAccountSettings(updateAccountSettingsOptions).execute();
AccountSettings accountSettings = response.getResult();

System.out.println(accountSettings);
Copy to clipboard

Example request

const params = {
  accountId: testAccountId,
  publicAccessEnabled: true,
};

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


// Feature
const featureModel = [
  {
    enabled: true,
    key: 'server.file_manager',
  },
  {
    enabled: true,
    key: 'server.web_preview',
  },
];

// RegionSetting
const regionSettingModel = [
  {
    enabled: true,
    key: 'eu-de',
  },
  {
    enabled: true,
    key: 'jp-tok',
  },
  {
    enabled: true,
    key: 'us-south',
  },
];

const params = {
  accountId: accountId,
  rev: '130-{accountId}',
  defaultEnableNewFeatures: true,
  defaultEnableNewRegions: true,
  enabled: true,
  features: featureModel,
  regions: regionSettingModel,
};


try {
  const res = await ibmCloudShellService.updateAccountSettings(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err)
}
Copy to clipboard

Example request

response = iam_access_groups_service.update_account_settings(
  account_id=test_account_id,
  public_access_enabled=True,
)
account_settings = response.get_result()

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


feature_model = [
  {
    'enabled': True,
    'key': 'server.file_manager',
  },
  {
    'enabled': True,
    'key': 'server.web_preview',
  },
]

region_setting_model = [
  {
    'enabled': True,
    'key': 'eu-de',
  },
  {
    'enabled': True,
    'key': 'jp-tok',
  },
  {
    'enabled': True,
    'key': 'us-south',
  },
]

account_settings = ibm_cloud_shell_service.update_account_settings(
  account_id=account_id,
  rev='130-12345678-abcd-1a2b-a1b2-1234567890ab',
  default_enable_new_features=False,
  default_enable_new_regions=True,
  enabled=True,
  features=feature_model,
  regions=region_setting_model,
).get_result()

print(json.dumps(account_settings, indent=2))
Copy to clipboard

Response

Response Body

AccountSettings

The access groups settings for a specific account.

AccountSettings

The access groups settings for a specific account.

AccountSettings

The access groups settings for a specific account.

AccountSettings

The access groups settings for a specific account.

AccountSettings

The access groups settings for a specific account.

Status Code

200
Settings Updated.
400
Bad Request.
401
Invalid Access Token.
403
Access Denied.
500
Internal Server Error.
503
Service Unavailable.

Example responses

Status 200

{
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS",
  "public_access_enabled": true
}
Copy to clipboard

Success example

{
  "account_id": "c56eec94cb5793b8da0eb7790759aaf0",
  "last_modified_at": "2019-01-01T01:01:00Z",
  "last_modified_by_id": "IBMid-06000260JS",
  "public_access_enabled": true
}
Copy to clipboard

Status 400

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_payload",
      "message": "Payload contains invalid/missing data. Reason: `Unexpected fields are present in the request body.`"
    }
  ],
  "status_code": 400
}
Copy to clipboard

Error example

{
  "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "errors": [
    {
      "code": "invalid_payload",
      "message": "Payload contains invalid/missing data. Reason: `Unexpected fields are present in the request body.`"
    }
  ],
  "status_code": 400
}
Copy to clipboard

Status 401

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

Error example

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

Status 403

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

Error example

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

Status 500

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

Error example

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

Status 503

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

Error example

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

Create an access group template. Make sure that the template is generic enough to apply to multiple different child accounts. Before you can assign an access group template to child accounts, you must commit it so that no further changes can be made to the version.

POST /v1/group_templates

(iamAccessGroups *IamAccessGroupsV2) CreateTemplate(createTemplateOptions *CreateTemplateOptions) (result *TemplateResponse, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) CreateTemplateWithContext(ctx context.Context, createTemplateOptions *CreateTemplateOptions) (result *TemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<TemplateResponse> createTemplate(CreateTemplateOptions createTemplateOptions)
Copy to clipboard

createTemplate(params)

create_template(
        self,
        name: str,
        account_id: str,
        *,
        description: Optional[str] = None,
        group: Optional['AccessGroupRequest'] = None,
        policy_template_references: Optional[List['PolicyTemplates']] = None,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.group-template.create

Auditing

Calling this method generates the following auditing event.

iam-groups.group-template.create

Request

Instantiate the CreateTemplateOptions struct and set the fields to provide parameter values for the CreateTemplate method.

Use the CreateTemplateOptions.Builder to create a CreateTemplateOptions object that contains the parameter values for the createTemplate method.

Custom Headers

Transaction-Id
string
An optional transaction id for the request

Possible values: 1 ≤ length ≤ 50, Value must match regular expression ^[a-zA-Z0-9_-]+$

Request Body

Required*

TemplateRequest

Create Template Input Component

Examples:

parameter

WithContext method only

CreateTemplateOptions

The CreateTemplate options.

CreateTemplateOptions

The createTemplate options.

parameters

name
Required*
string
Give the access group template a unique name that doesn't conflict with an existing access group templates in the account.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /^[a-zA-Z0-9!@#$%^&*()_+{}:;\"'<>,.?\/|\\-\\s]+$/
Examples:
accountId
Required*
string
Enterprise account id in which the template will be created.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression /^[a-zA-Z0-9_-]+$/
Examples:
description
string
Assign an optional description for the access group template.

Possible values: 0 ≤ length ≤ 250, Value must match regular expression /^[a-zA-Z0-9!@#$%^&*()_+{}:;\"'<>,.?\/|\\-\\s]+$/
Examples:
group
Access Group Component.
policyTemplateReferences
Existing policy templates that you can reference to assign access in the Access group input component.

Possible values: 0 ≤ number of items ≤ 50
Examples:
transactionId
string
An optional transaction id for the request.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression /^[a-zA-Z0-9_-]+$/

parameters

name
Required*
str
Give the access group template a unique name that doesn't conflict with an existing access group templates in the account.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /^[a-zA-Z0-9!@#$%^&*()_+{}:;\"'<>,.?\/|\\-\\s]+$/
Examples:
account_id
Required*
str
Enterprise account id in which the template will be created.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression /^[a-zA-Z0-9_-]+$/
Examples:
description
str
Assign an optional description for the access group template.

Possible values: 0 ≤ length ≤ 250, Value must match regular expression /^[a-zA-Z0-9!@#$%^&*()_+{}:;\"'<>,.?\/|\\-\\s]+$/
Examples:
group
Access Group Component.
policy_template_references
Existing policy templates that you can reference to assign access in the Access group input component.

Possible values: 0 ≤ number of items ≤ 50
Examples:
transaction_id
str
An optional transaction id for the request.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression /^[a-zA-Z0-9_-]+$/

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "name": "IAM Admin Group template", "description": "This access group template allows admin access to all IAM platform services in the account.", "account_id": "accountID-123", "group": { "name": "IAM Admin Group", "description": "This access group template allows admin access to all IAM platform services in the account.", "members": { "users": [ "IBMid-50PJGPKYJJ", "IBMid-665000T8WY" ], "services": [ "iam-ServiceId-345", "iam-ServiceId-456" ], "action_controls": { "add": true, "remove": false } }, "assertions": { "rules": [ { "name": "Manager group rule", "expiration": 12, "realm_name": "https://idp.example.org/SAML2", "conditions": [ { "claim": "blueGroup", "operator": "CONTAINS", "value": "test-bluegroup-saml" } ], "action_controls": { "remove": false } }, { "name": "Developer group rule", "expiration": 12, "realm_name": "https://idp.example.org/SAML2", "conditions": [ { "claim": "yellowGroup", "operator": "CONTAINS", "value": "test-yellowGroup-saml" } ] } ], "action_controls": { "add": false, "remove": true } }, "action_controls": { "access": { "add": false } } }, "policy_template_references": [ { "id": "policyTemplateId-123", "version": "1" }, { "id": "policyTemplateId-234", "version": "1" } ] }'   "{base_url}/v1/group_templates"
Copy to clipboard

Example request

membersActionControlsModel := &iamaccessgroupsv2.MembersActionControls{
  Add:    core.BoolPtr(true),
  Remove: core.BoolPtr(false),
}

membersInputModel := &iamaccessgroupsv2.Members{
  Users:          []string{"IBMid-50PJGPKYJJ", "IBMid-665000T8WY"},
  ActionControls: membersActionControlsModel,
}

conditionInputModel := &iamaccessgroupsv2.Conditions{
  Claim:    core.StringPtr("blueGroup"),
  Operator: core.StringPtr("CONTAINS"),
  Value:    core.StringPtr(`"test-bluegroup-saml"`),
}

rulesActionControlsModel := &iamaccessgroupsv2.RuleActionControls{
  Remove: core.BoolPtr(false),
}

ruleInputModel := &iamaccessgroupsv2.AssertionsRule{
  Name:           core.StringPtr("Manager group rule"),
  Expiration:     core.Int64Ptr(int64(12)),
  RealmName:      core.StringPtr("https://idp.example.org/SAML2"),
  Conditions:     []iamaccessgroupsv2.Conditions{*conditionInputModel},
  ActionControls: rulesActionControlsModel,
}

assertionsActionControlsModel := &iamaccessgroupsv2.AssertionsActionControls{
  Add:    core.BoolPtr(false),
  Remove: core.BoolPtr(true),
}

assertionsInputModel := &iamaccessgroupsv2.Assertions{
  Rules:          []iamaccessgroupsv2.AssertionsRule{*ruleInputModel},
  ActionControls: assertionsActionControlsModel,
}

accessActionControlsModel := &iamaccessgroupsv2.AccessActionControls{
  Add: core.BoolPtr(false),
}

groupActionControlsModel := &iamaccessgroupsv2.GroupActionControls{
  Access: accessActionControlsModel,
}

accessGroupInputModel := &iamaccessgroupsv2.AccessGroupRequest{
  Name:           core.StringPtr("IAM Admin Group"),
  Description:    core.StringPtr("This access group template allows admin access to all IAM platform services in the account."),
  Members:        membersInputModel,
  Assertions:     assertionsInputModel,
  ActionControls: groupActionControlsModel,
}

policyTemplatesInputModel := &iamaccessgroupsv2.PolicyTemplates{
  ID:      &testPolicyTemplateID,
  Version: core.StringPtr("1"),
}

createTemplateOptions := iamAccessGroupsService.NewCreateTemplateOptions(
  "IAM Admin Group template",
  testAccountID,
)
createTemplateOptions.SetDescription("This access group template allows admin access to all IAM platform services in the account.")
createTemplateOptions.SetGroup(accessGroupInputModel)
createTemplateOptions.SetPolicyTemplateReferences([]iamaccessgroupsv2.PolicyTemplates{*policyTemplatesInputModel})

createTemplateResponse, response, err := iamAccessGroupsService.CreateTemplate(createTemplateOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(createTemplateResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

MembersActionControls membersActionControlsModel = new MembersActionControls.Builder()
        .add(true)
        .remove(false)
        .build();
Members membersModel = new Members.Builder()
        .users(java.util.Arrays.asList("IBMid-50PJGPKYJJ", "IBMid-665000T8WY"))
        .actionControls(membersActionControlsModel)
        .build();
Conditions conditionsModel = new Conditions.Builder()
        .claim("blueGroup")
        .operator("CONTAINS")
        .value("\"test-bluegroup-saml\"")
        .build();
RuleActionControls ruleActionControlsModel = new RuleActionControls.Builder()
        .remove(false)
        .build();
AssertionsRule assertionsRuleModel = new AssertionsRule.Builder()
        .name("Manager group rule")
        .expiration(Long.valueOf("12"))
        .realmName("https://idp.example.org/SAML2")
        .conditions(java.util.Arrays.asList(conditionsModel))
        .actionControls(ruleActionControlsModel)
        .build();
AssertionsActionControls assertionsActionControlsModel = new AssertionsActionControls.Builder()
        .add(false)
        .remove(true)
        .build();
Assertions assertionsModel = new Assertions.Builder()
        .rules(java.util.Arrays.asList(assertionsRuleModel))
        .actionControls(assertionsActionControlsModel)
        .build();
AccessActionControls accessActionControlsModel = new AccessActionControls.Builder()
        .add(false)
        .build();
GroupActionControls groupActionControlsModel = new GroupActionControls.Builder()
        .access(accessActionControlsModel)
        .build();
AccessGroupRequest accessGroupRequestModel = new AccessGroupRequest.Builder()
        .name("IAM Admin Group")
        .description("This access group template allows admin access to all IAM platform services in the account.")
        .members(membersModel)
        .assertions(assertionsModel)
        .actionControls(groupActionControlsModel)
        .build();
PolicyTemplates policyTemplatesModel = new PolicyTemplates.Builder()
        .id(testPolicyTemplateId)
        .version("1")
        .build();
CreateTemplateOptions createTemplateOptions = new CreateTemplateOptions.Builder()
        .name("IAM Admin Group template")
        .accountId(testAccountId)
        .description("This access group template allows admin access to all IAM platform services in the account.")
        .group(accessGroupRequestModel)
        .policyTemplateReferences(java.util.Arrays.asList(policyTemplatesModel))
        .build();

Response<TemplateResponse> response = iamAccessGroupsService.createTemplate(createTemplateOptions).execute();
TemplateResponse templateResponse = response.getResult();

System.out.println(templateResponse);
Copy to clipboard

Example request

// Request models needed by this operation.

// MembersActionControls
const membersActionControlsModel = {
  add: true,
  remove: false,
};

// MembersInput
const membersInputModel = {
  users: ['IBMid-50PJGPKYJJ', 'IBMid-665000T8WY'],
  action_controls: membersActionControlsModel,
};

// ConditionInput
const conditionInputModel = {
  claim: 'blueGroup',
  operator: 'CONTAINS',
  value: '\"test-bluegroup-saml\"',
};

// RulesActionControls
const rulesActionControlsModel = {
  remove: false,
};

// RuleInput
const ruleInputModel = {
  name: 'Manager group rule',
  expiration: 12,
  realm_name: 'https://idp.example.org/SAML2',
  conditions: [conditionInputModel],
  action_controls: rulesActionControlsModel,
};

// AssertionsActionControls
const assertionsActionControlsModel = {
  add: false,
  remove: true,
};

// AssertionsInput
const assertionsInputModel = {
  rules: [ruleInputModel],
  action_controls: assertionsActionControlsModel,
};

// AccessActionControls
const accessActionControlsModel = {
  add: false,
};

// GroupActionControls
const groupActionControlsModel = {
  access: accessActionControlsModel,
};

// AccessGroupInput
const accessGroupInputModel = {
  name: 'IAM Admin Group',
  description: 'This access group template allows admin access to all IAM platform services in the account.',
  members: membersInputModel,
  assertions: assertionsInputModel,
  action_controls: groupActionControlsModel,
};

// PolicyTemplatesInput
const policyTemplatesInputModel = {
  id: testPolicyTemplateId,
  version: '1',
};

const params = {
  name: 'IAM Admin Group template',
  accountId: testAccountId,
  description: 'This access group template allows admin access to all IAM platform services in the account.',
  group: accessGroupInputModel,
  policyTemplateReferences: [policyTemplatesInputModel],
};

let res;
try {
  res = await iamAccessGroupsService.createTemplate(params);
  testTemplateId = res.result.id;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

members_action_controls_model = {
  'add': True,
  'remove': False,
}

members_input_model = {
  'users': ['IBMid-50PJGPKYJJ', 'IBMid-665000T8WY'],
  'action_controls': members_action_controls_model,
}

condition_input_model = {
  'claim': 'blueGroup',
  'operator': 'CONTAINS',
  'value': '\"test-bluegroup-saml\"',
}

rules_action_controls_model = {
  'remove': False,
}

rule_input_model = {
  'name': 'Manager group rule',
  'expiration': 12,
  'realm_name': 'https://idp.example.org/SAML2',
  'conditions': [condition_input_model],
  'action_controls': rules_action_controls_model,
}

assertions_action_controls_model = {
  'add': False,
  'remove': True,
}

assertions_input_model = {
  'rules': [rule_input_model],
  'action_controls': assertions_action_controls_model,
}

access_action_controls_model = {
  'add': False,
}

group_action_controls_model = {
  'access': access_action_controls_model,
}

access_group_input_model = {
  'name': 'IAM Admin Group',
  'description': 'This access group template allows admin access to all IAM platform services in the account.',
  'members': members_input_model,
  'assertions': assertions_input_model,
  'action_controls': group_action_controls_model,
}

policy_templates_input_model = {
  'id': test_policy_template_id,
  'version': '1',
}

response = iam_access_groups_service.create_template(
  name='IAM Admin Group template',
  account_id=test_account_id,
  description='This access group template allows admin access to all IAM platform services in the account.',
  group=access_group_input_model,
  policy_template_references=[policy_templates_input_model],
)
create_template_response = response.get_result()

print(json.dumps(create_template_response, indent=2))
Copy to clipboard

Response

Response Body

TemplateResponse

Response output for template

TemplateResponse

Response output for template.

TemplateResponse

Response output for template.

TemplateResponse

Response output for template.

TemplateResponse

Response output for template.

Status Code

201
Successful response
400
Bad request
401
Unauthorized
403
Access denied
409
Template Conflict Error
429
Templates per account limit reached
500
Internal server error

Example responses

Status 201

{
  "id": "AccessGroupTemplateId-93ac0a21-d130-490f-8e32-4615e242a161",
  "name": "IAM Admin Group template",
  "description": "This template allows admin access to all IAM platform service.",
  "account_id": "accountID-123",
  "version": "1",
  "committed": false,
  "group": {
    "name": "IAM Admin Group",
    "description": "This AG allows admin access to all IAM platform services.",
    "members": {
      "users": [
        "IBMid-123",
        "IBMid-234"
      ],
      "services": [
        "iam-ServiceId-345",
        "iam-ServiceId-456"
      ],
      "action_controls": {
        "add": true,
        "remove": false
      }
    },
    "assertions": {
      "rules": [
        {
          "name": "Developer group rule",
          "expiration": 12,
          "realm_name": "https://idp.example.org/SAML2",
          "conditions": [
            {
              "claim": "yellowGroup",
              "operator": "CONTAINS",
              "value": "test-yellowGroup-saml"
            }
          ],
          "action_controls": {
            "remove": true
          }
        },
        {
          "name": "Manager group rule",
          "expiration": 12,
          "realm_name": "https://idp.example.org/SAML2",
          "conditions": [
            {
              "claim": "blueGroup",
              "operator": "CONTAINS",
              "value": "test-bluegroup-saml"
            }
          ],
          "action_controls": {
            "remove": false
          }
        }
      ],
      "action_controls": {
        "add": false,
        "remove": true
      }
    },
    "action_controls": {
      "access": {
        "add": false
      }
    }
  },
  "policy_template_references": [
    {
      "id": "policyTemplateId-123",
      "version": "1"
    },
    {
      "id": "policyTemplateId-234",
      "version": "1"
    }
  ],
  "href": "\"https://iam.cloud.ibm.com/v1/group_templates/AccessGroupTemplateId-93ac0a21-d130-490f-8e32-4615e242a161\"",
  "created_at": "2023-02-13T14:28:18.000Z",
  "created_by_id": "IBMid-1234",
  "last_modified_at": "2023-02-13T14:28:18.000Z",
  "last_modified_by_id": "IBMid-1234"
}
Copy to clipboard

Success example

{
  "id": "AccessGroupTemplateId-93ac0a21-d130-490f-8e32-4615e242a161",
  "name": "IAM Admin Group template",
  "description": "This template allows admin access to all IAM platform service.",
  "account_id": "accountID-123",
  "version": "1",
  "committed": false,
  "group": {
    "name": "IAM Admin Group",
    "description": "This AG allows admin access to all IAM platform services.",
    "members": {
      "users": [
        "IBMid-123",
        "IBMid-234"
      ],
      "services": [
        "iam-ServiceId-345",
        "iam-ServiceId-456"
      ],
      "action_controls": {
        "add": true,
        "remove": false
      }
    },
    "assertions": {
      "rules": [
        {
          "name": "Developer group rule",
          "expiration": 12,
          "realm_name": "https://idp.example.org/SAML2",
          "conditions": [
            {
              "claim": "yellowGroup",
              "operator": "CONTAINS",
              "value": "test-yellowGroup-saml"
            }
          ],
          "action_controls": {
            "remove": true
          }
        },
        {
          "name": "Manager group rule",
          "expiration": 12,
          "realm_name": "https://idp.example.org/SAML2",
          "conditions": [
            {
              "claim": "blueGroup",
              "operator": "CONTAINS",
              "value": "test-bluegroup-saml"
            }
          ],
          "action_controls": {
            "remove": false
          }
        }
      ],
      "action_controls": {
        "add": false,
        "remove": true
      }
    },
    "action_controls": {
      "access": {
        "add": false
      }
    }
  },
  "policy_template_references": [
    {
      "id": "policyTemplateId-123",
      "version": "1"
    },
    {
      "id": "policyTemplateId-234",
      "version": "1"
    }
  ],
  "href": "\"https://iam.cloud.ibm.com/v1/group_templates/AccessGroupTemplateId-93ac0a21-d130-490f-8e32-4615e242a161\"",
  "created_at": "2023-02-13T14:28:18.000Z",
  "created_by_id": "IBMid-1234",
  "last_modified_at": "2023-02-13T14:28:18.000Z",
  "last_modified_by_id": "IBMid-1234"
}
Copy to clipboard

List the access group templates in an enterprise account.

GET /v1/group_templates

(iamAccessGroups *IamAccessGroupsV2) ListTemplates(listTemplatesOptions *ListTemplatesOptions) (result *ListTemplatesResponse, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) ListTemplatesWithContext(ctx context.Context, listTemplatesOptions *ListTemplatesOptions) (result *ListTemplatesResponse, response *core.DetailedResponse, err error)

ServiceCall<ListTemplatesResponse> listTemplates(ListTemplatesOptions listTemplatesOptions)
Copy to clipboard

listTemplates(params)

list_templates(
        self,
        account_id: str,
        *,
        transaction_id: Optional[str] = None,
        limit: Optional[int] = None,
        offset: Optional[int] = None,
        verbose: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.group-template.read

Auditing

Calling this method generates the following auditing event.

iam-groups.group-template.read

Request

Instantiate the ListTemplatesOptions struct and set the fields to provide parameter values for the ListTemplates method.

Use the ListTemplatesOptions.Builder to create a ListTemplatesOptions object that contains the parameter values for the listTemplates method.

Custom Headers

Transaction-Id
string
An optional transaction id for the request

Possible values: 1 ≤ length ≤ 50, Value must match regular expression ^[a-zA-Z0-9_-]+$

Query Parameters

account_id
Required*
string
Enterprise account ID

Possible values: 1 ≤ length ≤ 50, Value must match regular expression ^[a-zA-Z0-9_-]+$
Example: accountID-123
limit
integer
Return up to this limit of results where limit is between 0 and 100.

Possible values: value ≤ 100
Default: 50
Example: 50
offset
integer
The offset of the first result item to be returned.
verbose
boolean
If verbose=true, IAM resource details are returned. If performance is a concern, leave the verbose parameter off so that details are not retrieved.

Example: true

parameter

WithContext method only

ListTemplatesOptions

The ListTemplates options.

ListTemplatesOptions

The listTemplates options.

parameters

accountId
Required*
string
Enterprise account ID.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression /^[a-zA-Z0-9_-]+$/
Examples:
transactionId
string
An optional transaction id for the request.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression /^[a-zA-Z0-9_-]+$/
limit
number
Return up to this limit of results where limit is between 0 and 100.

Possible values: value ≤ 100
Default: 50
Examples:
offset
number
The offset of the first result item to be returned.
Examples:
verbose
boolean
If verbose=true, IAM resource details are returned. If performance is a concern, leave the verbose parameter off so that details are not retrieved.
Examples:

parameters

account_id
Required*
str
Enterprise account ID.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression /^[a-zA-Z0-9_-]+$/
Examples:
transaction_id
str
An optional transaction id for the request.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression /^[a-zA-Z0-9_-]+$/
limit
int
Return up to this limit of results where limit is between 0 and 100.

Possible values: value ≤ 100
Default: 50
Examples:
offset
int
The offset of the first result item to be returned.
Examples:
verbose
bool
If verbose=true, IAM resource details are returned. If performance is a concern, leave the verbose parameter off so that details are not retrieved.
Examples:

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v1/group_templates?account_id=accountID-123&limit=50&offset=0&verbose=true"
Copy to clipboard

Example request

listTemplatesOptions := &iamaccessgroupsv2.ListTemplatesOptions{
  AccountID:     &testAccountID,
  TransactionID: core.StringPtr("testString"),
  Limit:         core.Int64Ptr(int64(50)),
  Verbose:       core.BoolPtr(true),
}

pager, err := iamAccessGroupsService.NewTemplatesPager(listTemplatesOptions)
if err != nil {
  panic(err)
}

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

Example request

ListTemplatesOptions listTemplatesOptions = new ListTemplatesOptions.Builder()
        .accountId(testAccountId)
        .transactionId("testString")
        .limit(Long.valueOf("50"))
        .verbose(true)
        .build();

TemplatesPager pager = new TemplatesPager(iamAccessGroupsService, listTemplatesOptions);
List<GroupTemplate> allResults = new ArrayList<>();
while (pager.hasNext()) {
    List<GroupTemplate> nextPage = pager.getNext();
    allResults.addAll(nextPage);
}

System.out.println(GsonSingleton.getGson().toJson(allResults));
Copy to clipboard

Example request

const params = {
  accountId: testAccountId,
  transactionId: 'testString',
  limit: 50,
};

const allResults = [];
try {
  const pager = new IamAccessGroupsV2.TemplatesPager(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);
}
Copy to clipboard

Example request

all_results = []
pager = TemplatesPager(
  client=iam_access_groups_service,
  account_id=test_account_id,
  transaction_id='testString',
  limit=50,
  verbose=True,
)
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))
Copy to clipboard

Response

Response Body

ListTemplatesResponse

Response object for listing templates

ListTemplatesResponse

Response object for listing templates.

ListTemplatesResponse

Response object for listing templates.

ListTemplatesResponse

Response object for listing templates.

ListTemplatesResponse

Response object for listing templates.

Status Code

200
Successful response
401
Unauthorized
403
Access denied
500
Internal server error

Example responses

Status 200

{
  "limit": 100,
  "offset": 0,
  "total_count": 3,
  "first": {
    "href": "\"https://iam.cloud.ibm.com/v1/group_templates?limit=100&account_id=accountID-123&verbose=true\""
  },
  "last": {
    "href": "\"https://iam.cloud.ibm.com/v1/group_templates?offset=0&limit=100&account_id=accountID-123&verbose=true\""
  },
  "group_templates": [
    {
      "id": "AccessGroupTemplateId-f5c3b076-334a-48c6-906f-8120de1b4321",
      "name": "IAM Admin developers template",
      "description": "This access group template allows developers access to all IAM platform services in the account.",
      "version": "1",
      "committed": false,
      "group": {
        "name": "IAM developers Group",
        "description": "This access group template allows developers access to all IAM platform services in the account.",
        "members": {
          "users": [
            "IBMid-123",
            "IBMid-234"
          ],
          "services": [
            "iam-ServiceId-345",
            "iam-ServiceId-456"
          ],
          "action_controls": {
            "add": true,
            "remove": false
          }
        },
        "assertions": {
          "rules": [
            {
              "name": "Developer group rule",
              "expiration": 12,
              "realm_name": "https://idp.example.org/SAML2",
              "conditions": [
                {
                  "claim": "yellowGroup",
                  "operator": "CONTAINS",
                  "value": "test-yellowGroup-saml"
                }
              ],
              "action_controls": {
                "remove": false
              }
            },
            {
              "name": "Manager group rule",
              "expiration": 12,
              "realm_name": "https://idp.example.org/SAML2",
              "conditions": [
                {
                  "claim": "blueGroup",
                  "operator": "CONTAINS",
                  "value": "test-bluegroup-saml"
                }
              ],
              "action_controls": {
                "remove": false
              }
            }
          ],
          "action_controls": {
            "add": false,
            "remove": true
          }
        },
        "action_controls": {
          "access": {
            "add": false
          }
        }
      },
      "policy_template_references": [
        {
          "id": "policyTemplateId-123",
          "version": "1"
        },
        {
          "id": "policyTemplateId-234",
          "version": "1"
        }
      ],
      "href": "\"https://iam.cloud.ibm.com/v1/group_templates/AccessGroupTemplateId-f5c3b076-334a-48c6-906f-8120de1b4321/1\"",
      "created_at": "2023-02-13T10:44:15.000Z",
      "created_by_id": "IBMid-1234",
      "last_modified_at": "2023-02-13T10:44:15.000Z",
      "last_modified_by_id": "IBMid-1234"
    },
    {
      "id": "AccessGroupTemplateId-93ac0a21-d130-490f-8e32-4615e242a161",
      "name": "IAM Admin Group template 3",
      "description": "This access group template allows admin access to all IAM platform services in the account.",
      "version": "1",
      "committed": false,
      "group": {
        "name": "IAM Admin Group 3",
        "description": "This access group template allows admin access to all IAM platform services in the account.",
        "members": {
          "users": [
            "IBMid-123",
            "IBMid-234"
          ],
          "services": [
            "iam-ServiceId-345",
            "iam-ServiceId-456"
          ],
          "action_controls": {
            "add": true,
            "remove": false
          }
        },
        "assertions": {
          "rules": [
            {
              "name": "Developer group rule",
              "expiration": 12,
              "realm_name": "https://idp.example.org/SAML2",
              "conditions": [
                {
                  "claim": "yellowGroup",
                  "operator": "CONTAINS",
                  "value": "test-yellowGroup-saml"
                }
              ],
              "action_controls": {
                "remove": true
              }
            },
            {
              "name": "Manager group rule",
              "expiration": 12,
              "realm_name": "https://idp.example.org/SAML2",
              "conditions": [
                {
                  "claim": "blueGroup",
                  "operator": "CONTAINS",
                  "value": "test-bluegroup-saml"
                }
              ],
              "action_controls": {
                "remove": false
              }
            }
          ],
          "action_controls": {
            "add": false,
            "remove": true
          }
        },
        "action_controls": {
          "access": {
            "add": false
          }
        }
      },
      "policy_template_references": [
        {
          "id": "policyTemplateId-123",
          "version": "1"
        },
        {
          "id": "policyTemplateId-234",
          "version": "1"
        }
      ],
      "href": "\"https://iam.cloud.ibm.com/v1/group_templates/AccessGroupTemplateId-93ac0a21-d130-490f-8e32-4615e242a161/1\"",
      "created_at": "2023-02-13T14:28:18.000Z",
      "created_by_id": "IBMid-12345",
      "last_modified_at": "2023-02-13T14:28:18.000Z",
      "last_modified_by_id": "IBMid-12345"
    },
    {
      "id": "AccessGroupTemplateId-255cf72c-0425-4e10-8721-b0dcbe1f1a8e",
      "name": "IAM Admin Group template for deployment version 1",
      "description": "This access group template allows admin access to all IAM platform services in the account ID.",
      "version": "8",
      "committed": false,
      "group": {
        "name": "IAM Admin Group for deployment version 1",
        "description": "This access group template allows admin access to all IAM platform services in the account.",
        "members": {
          "users": [
            "IBMid-123",
            "IBMid-234"
          ],
          "services": [
            "iam-ServiceId-345",
            "iam-ServiceId-456"
          ],
          "action_controls": {
            "add": true,
            "remove": true
          }
        },
        "assertions": {
          "rules": [
            {
              "name": "Manager group rule",
              "expiration": 12,
              "realm_name": "https://idp.example.org/SAML2",
              "conditions": [
                {
                  "claim": "blueGroup",
                  "operator": "CONTAINS",
                  "value": "test-bluegroup-saml"
                }
              ],
              "action_controls": {
                "remove": true
              }
            }
          ],
          "action_controls": {
            "add": true,
            "remove": true
          }
        },
        "action_controls": {
          "access": {
            "add": true
          }
        }
      },
      "policy_template_references": [
        {
          "id": "policyTemplateId-123",
          "version": "1"
        },
        {
          "id": "policyTemplateId-234",
          "version": "1"
        }
      ],
      "href": "\"https://iam.cloud.ibm.com/v1/group_templates/AccessGroupTemplateId-255cf72c-0425-4e10-8721-b0dcbe1f1a8e/8\"",
      "created_at": "2023-02-10T11:49:17.000Z",
      "created_by_id": "IBMid-12345",
      "last_modified_at": "2023-02-10T11:49:17.000Z",
      "last_modified_by_id": "IBMid-12345"
    }
  ]
}
Copy to clipboard

Success example

{
  "limit": 100,
  "offset": 0,
  "total_count": 3,
  "first": {
    "href": "\"https://iam.cloud.ibm.com/v1/group_templates?limit=100&account_id=accountID-123&verbose=true\""
  },
  "last": {
    "href": "\"https://iam.cloud.ibm.com/v1/group_templates?offset=0&limit=100&account_id=accountID-123&verbose=true\""
  },
  "group_templates": [
    {
      "id": "AccessGroupTemplateId-f5c3b076-334a-48c6-906f-8120de1b4321",
      "name": "IAM Admin developers template",
      "description": "This access group template allows developers access to all IAM platform services in the account.",
      "version": "1",
      "committed": false,
      "group": {
        "name": "IAM developers Group",
        "description": "This access group template allows developers access to all IAM platform services in the account.",
        "members": {
          "users": [
            "IBMid-123",
            "IBMid-234"
          ],
          "services": [
            "iam-ServiceId-345",
            "iam-ServiceId-456"
          ],
          "action_controls": {
            "add": true,
            "remove": false
          }
        },
        "assertions": {
          "rules": [
            {
              "name": "Developer group rule",
              "expiration": 12,
              "realm_name": "https://idp.example.org/SAML2",
              "conditions": [
                {
                  "claim": "yellowGroup",
                  "operator": "CONTAINS",
                  "value": "test-yellowGroup-saml"
                }
              ],
              "action_controls": {
                "remove": false
              }
            },
            {
              "name": "Manager group rule",
              "expiration": 12,
              "realm_name": "https://idp.example.org/SAML2",
              "conditions": [
                {
                  "claim": "blueGroup",
                  "operator": "CONTAINS",
                  "value": "test-bluegroup-saml"
                }
              ],
              "action_controls": {
                "remove": false
              }
            }
          ],
          "action_controls": {
            "add": false,
            "remove": true
          }
        },
        "action_controls": {
          "access": {
            "add": false
          }
        }
      },
      "policy_template_references": [
        {
          "id": "policyTemplateId-123",
          "version": "1"
        },
        {
          "id": "policyTemplateId-234",
          "version": "1"
        }
      ],
      "href": "\"https://iam.cloud.ibm.com/v1/group_templates/AccessGroupTemplateId-f5c3b076-334a-48c6-906f-8120de1b4321/1\"",
      "created_at": "2023-02-13T10:44:15.000Z",
      "created_by_id": "IBMid-1234",
      "last_modified_at": "2023-02-13T10:44:15.000Z",
      "last_modified_by_id": "IBMid-1234"
    },
    {
      "id": "AccessGroupTemplateId-93ac0a21-d130-490f-8e32-4615e242a161",
      "name": "IAM Admin Group template 3",
      "description": "This access group template allows admin access to all IAM platform services in the account.",
      "version": "1",
      "committed": false,
      "group": {
        "name": "IAM Admin Group 3",
        "description": "This access group template allows admin access to all IAM platform services in the account.",
        "members": {
          "users": [
            "IBMid-123",
            "IBMid-234"
          ],
          "services": [
            "iam-ServiceId-345",
            "iam-ServiceId-456"
          ],
          "action_controls": {
            "add": true,
            "remove": false
          }
        },
        "assertions": {
          "rules": [
            {
              "name": "Developer group rule",
              "expiration": 12,
              "realm_name": "https://idp.example.org/SAML2",
              "conditions": [
                {
                  "claim": "yellowGroup",
                  "operator": "CONTAINS",
                  "value": "test-yellowGroup-saml"
                }
              ],
              "action_controls": {
                "remove": true
              }
            },
            {
              "name": "Manager group rule",
              "expiration": 12,
              "realm_name": "https://idp.example.org/SAML2",
              "conditions": [
                {
                  "claim": "blueGroup",
                  "operator": "CONTAINS",
                  "value": "test-bluegroup-saml"
                }
              ],
              "action_controls": {
                "remove": false
              }
            }
          ],
          "action_controls": {
            "add": false,
            "remove": true
          }
        },
        "action_controls": {
          "access": {
            "add": false
          }
        }
      },
      "policy_template_references": [
        {
          "id": "policyTemplateId-123",
          "version": "1"
        },
        {
          "id": "policyTemplateId-234",
          "version": "1"
        }
      ],
      "href": "\"https://iam.cloud.ibm.com/v1/group_templates/AccessGroupTemplateId-93ac0a21-d130-490f-8e32-4615e242a161/1\"",
      "created_at": "2023-02-13T14:28:18.000Z",
      "created_by_id": "IBMid-12345",
      "last_modified_at": "2023-02-13T14:28:18.000Z",
      "last_modified_by_id": "IBMid-12345"
    },
    {
      "id": "AccessGroupTemplateId-255cf72c-0425-4e10-8721-b0dcbe1f1a8e",
      "name": "IAM Admin Group template for deployment version 1",
      "description": "This access group template allows admin access to all IAM platform services in the account ID.",
      "version": "8",
      "committed": false,
      "group": {
        "name": "IAM Admin Group for deployment version 1",
        "description": "This access group template allows admin access to all IAM platform services in the account.",
        "members": {
          "users": [
            "IBMid-123",
            "IBMid-234"
          ],
          "services": [
            "iam-ServiceId-345",
            "iam-ServiceId-456"
          ],
          "action_controls": {
            "add": true,
            "remove": true
          }
        },
        "assertions": {
          "rules": [
            {
              "name": "Manager group rule",
              "expiration": 12,
              "realm_name": "https://idp.example.org/SAML2",
              "conditions": [
                {
                  "claim": "blueGroup",
                  "operator": "CONTAINS",
                  "value": "test-bluegroup-saml"
                }
              ],
              "action_controls": {
                "remove": true
              }
            }
          ],
          "action_controls": {
            "add": true,
            "remove": true
          }
        },
        "action_controls": {
          "access": {
            "add": true
          }
        }
      },
      "policy_template_references": [
        {
          "id": "policyTemplateId-123",
          "version": "1"
        },
        {
          "id": "policyTemplateId-234",
          "version": "1"
        }
      ],
      "href": "\"https://iam.cloud.ibm.com/v1/group_templates/AccessGroupTemplateId-255cf72c-0425-4e10-8721-b0dcbe1f1a8e/8\"",
      "created_at": "2023-02-10T11:49:17.000Z",
      "created_by_id": "IBMid-12345",
      "last_modified_at": "2023-02-10T11:49:17.000Z",
      "last_modified_by_id": "IBMid-12345"
    }
  ]
}
Copy to clipboard

Create a new version of an access group template.

POST /v1/group_templates/{template_id}/versions

(iamAccessGroups *IamAccessGroupsV2) CreateTemplateVersion(createTemplateVersionOptions *CreateTemplateVersionOptions) (result *TemplateVersionResponse, response *core.DetailedResponse, err error)

(iamAccessGroups *IamAccessGroupsV2) CreateTemplateVersionWithContext(ctx context.Context, createTemplateVersionOptions *CreateTemplateVersionOptions) (result *TemplateVersionResponse, response *core.DetailedResponse, err error)

ServiceCall<TemplateVersionResponse> createTemplateVersion(CreateTemplateVersionOptions createTemplateVersionOptions)
Copy to clipboard

createTemplateVersion(params)

create_template_version(
        self,
        template_id: str,
        *,
        name: Optional[str] = None,
        description: Optional[str] = None,
        group: Optional['AccessGroupRequest'] = None,
        policy_template_references: Optional[List['PolicyTemplates']] = None,
        transaction_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.group-template.create

Auditing

Calling this method generates the following auditing event.

iam-groups.group-template.create

Request

Instantiate the CreateTemplateVersionOptions struct and set the fields to provide parameter values for the CreateTemplateVersion method.

Use the CreateTemplateVersionOptions.Builder to create a CreateTemplateVersionOptions object that contains the parameter values for the createTemplateVersion method.

Custom Headers

Transaction-Id
string
An optional transaction id for the request

Possible values: 1 ≤ length ≤ 50, Value must match regular expression ^[a-zA-Z0-9_-]+$

Path Parameters

template_id
Required*
string
ID of the template that you want to create a new version of

Possible values: 1 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9_-]+$

Request Body

TemplateVersionRequest

Create Template Version Input component

Examples:

parameter

WithContext method only

CreateTemplateVersionOptions

The CreateTemplateVersion options.

CreateTemplateVersionOptions

The createTemplateVersion options.

parameters

templateId
Required*
string
ID of the template that you want to create a new version of.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /^[a-zA-Z0-9_-]+$/
name
string
This is an optional field. If the field is included it will change the name value for all existing versions of the template..

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /^[a-zA-Z0-9!@#$%^&*()_+{}:;\"'<>,.?\/|\\-\\s]+$/
Examples:
description
string
Assign an optional description for the access group template version.

Possible values: 0 ≤ length ≤ 250, Value must match regular expression /^[a-zA-Z0-9!@#$%^&*()_+{}:;\"'<>,.?\/|\\-\\s]+$/
Examples:
group
Access Group Component.
policyTemplateReferences
The policy templates associated with the template version.

Possible values: 0 ≤ number of items ≤ 50
Examples:
transactionId
string
An optional transaction id for the request.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression /^[a-zA-Z0-9_-]+$/

parameters

template_id
Required*
str
ID of the template that you want to create a new version of.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /^[a-zA-Z0-9_-]+$/
name
str
This is an optional field. If the field is included it will change the name value for all existing versions of the template..

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /^[a-zA-Z0-9!@#$%^&*()_+{}:;\"'<>,.?\/|\\-\\s]+$/
Examples:
description
str
Assign an optional description for the access group template version.

Possible values: 0 ≤ length ≤ 250, Value must match regular expression /^[a-zA-Z0-9!@#$%^&*()_+{}:;\"'<>,.?\/|\\-\\s]+$/
Examples:
group
Access Group Component.
policy_template_references
The policy templates associated with the template version.

Possible values: 0 ≤ number of items ≤ 50
Examples:
transaction_id
str
An optional transaction id for the request.

Possible values: 1 ≤ length ≤ 50, Value must match regular expression /^[a-zA-Z0-9_-]+$/

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "name": "IAM Admin Group template 2", "description": "This access group template allows admin access to all IAM platform services in the account.", "group": { "name": "IAM Admin Group 8", "description": "This access group template allows admin access to all IAM platform services in the account.", "members": { "users": [ "IBMid-50PJGPKYJJ", "IBMid-665000T8WY" ], "services": [ "iam-ServiceId-345" ], "action_controls": { "add": true, "remove": false } }, "assertions": { "rules": [ { "name": "Manager group rule", "expiration": 12, "realm_name": "https://idp.example.org/SAML2", "conditions": [ { "claim": "blueGroup", "operator": "CONTAINS", "value": "test-bluegroup-saml" } ], "action_controls": { "remove": false } } ], "action_controls": { "add": false } }, "action_controls": { "access": { "add": false } } }, "policy_template_references": [ { "id": "policyTemplateId-123", "version": "1" }, { "id": "policyTemplateId-234", "version": "1" } ] }'   "{base_url}/v1/group_templates/{template_id}/versions"
Copy to clipboard

Example request

membersActionControlsModel := &iamaccessgroupsv2.MembersActionControls{
  Add:    core.BoolPtr(true),
  Remove: core.BoolPtr(false),
}

membersInputModel := &iamaccessgroupsv2.Members{
  Users:          []string{"IBMid-50PJGPKYJJ", "IBMid-665000T8WY"},
  ActionControls: membersActionControlsModel,
}

conditionInputModel := &iamaccessgroupsv2.Conditions{
  Claim:    core.StringPtr("blueGroup"),
  Operator: core.StringPtr("CONTAINS"),
  Value:    core.StringPtr(`"test-bluegroup-saml"`),
}

ruleInputModel := &iamaccessgroupsv2.AssertionsRule{
  Name:       core.StringPtr("Manager group rule"),
  Expiration: core.Int64Ptr(int64(12)),
  RealmName:  core.StringPtr("https://idp.example.org/SAML2"),
  Conditions: []iamaccessgroupsv2.Conditions{*conditionInputModel},
}

assertionsActionControlsModel := &iamaccessgroupsv2.AssertionsActionControls{
  Add: core.BoolPtr(false),
}

assertionsInputModel := &iamaccessgroupsv2.Assertions{
  Rules:          []iamaccessgroupsv2.AssertionsRule{*ruleInputModel},
  ActionControls: assertionsActionControlsModel,
}

accessActionControlsModel := &iamaccessgroupsv2.AccessActionControls{
  Add: core.BoolPtr(false),
}

groupActionControlsModel := &iamaccessgroupsv2.GroupActionControls{
  Access: accessActionControlsModel,
}

accessGroupInputModel := &iamaccessgroupsv2.AccessGroupRequest{
  Name:           core.StringPtr("IAM Admin Group 8"),
  Description:    core.StringPtr("This access group template allows admin access to all IAM platform services in the account."),
  Members:        membersInputModel,
  Assertions:     assertionsInputModel,
  ActionControls: groupActionControlsModel,
}

policyTemplatesInputModel := &iamaccessgroupsv2.PolicyTemplates{
  ID:      &testPolicyTemplateID,
  Version: core.StringPtr("1"),
}

createTemplateVersionOptions := iamAccessGroupsService.NewCreateTemplateVersionOptions(
  testTemplateId,
)
createTemplateVersionOptions.SetName("IAM Admin Group template 2")
createTemplateVersionOptions.SetDescription("This access group template allows admin access to all IAM platform services in the account.")
createTemplateVersionOptions.SetGroup(accessGroupInputModel)
createTemplateVersionOptions.SetPolicyTemplateReferences([]iamaccessgroupsv2.PolicyTemplates{*policyTemplatesInputModel})

createTemplateResponse, response, err := iamAccessGroupsService.CreateTemplateVersion(createTemplateVersionOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(createTemplateResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

MembersActionControls membersActionControlsModel = new MembersActionControls.Builder()
        .add(true)
        .remove(false)
        .build();
Members membersModel = new Members.Builder()
        .users(java.util.Arrays.asList("IBMid-50PJGPKYJJ", "IBMid-665000T8WY"))
        .actionControls(membersActionControlsModel)
        .build();
Conditions conditionsModel = new Conditions.Builder()
        .claim("blueGroup")
        .operator("CONTAINS")
        .value("\"test-bluegroup-saml\"")
        .build();
AssertionsRule assertionsRuleModel = new AssertionsRule.Builder()
        .name("Manager group rule")
        .expiration(Long.valueOf("12"))
        .realmName("https://idp.example.org/SAML2")
        .conditions(java.util.Arrays.asList(conditionsModel))
        .build();
AssertionsActionControls assertionsActionControlsModel = new AssertionsActionControls.Builder()
        .add(false)
        .build();
Assertions assertionsModel = new Assertions.Builder()
        .rules(java.util.Arrays.asList(assertionsRuleModel))
        .actionControls(assertionsActionControlsModel)
        .build();
AccessActionControls accessActionControlsModel = new AccessActionControls.Builder()
        .add(false)
        .build();
GroupActionControls groupActionControlsModel = new GroupActionControls.Builder()
        .access(accessActionControlsModel)
        .build();
AccessGroupRequest accessGroupRequestModel = new AccessGroupRequest.Builder()
        .name("IAM Admin Group 8")
        .description("This access group template allows admin access to all IAM platform services in the account.")
        .members(membersModel)
        .assertions(assertionsModel)
        .actionControls(groupActionControlsModel)
        .build();
PolicyTemplates policyTemplatesModel = new PolicyTemplates.Builder()
        .id(testPolicyTemplateId)
        .version("1")
        .build();
CreateTemplateVersionOptions createTemplateVersionOptions = new CreateTemplateVersionOptions.Builder()
        .templateId(testTemplateId)
        .name("IAM Admin Group template 2")
        .description("This access group template allows admin access to all IAM platform services in the account.")
        .group(accessGroupRequestModel)
        .policyTemplateReferences(java.util.Arrays.asList(policyTemplatesModel))
        .build();

Response<TemplateVersionResponse> response = iamAccessGroupsService.createTemplateVersion(createTemplateVersionOptions).execute();
TemplateVersionResponse templateVersionResponse = response.getResult();

System.out.println(templateVersionResponse);
Copy to clipboard

Example request

// Request models needed by this operation.

// MembersActionControls
const membersActionControlsModel = {
  add: true,
  remove: false,
};

// MembersInput
const membersInputModel = {
  users: ['IBMid-50PJGPKYJJ', 'IBMid-665000T8WY'],
  action_controls: membersActionControlsModel,
};

// ConditionInput
const conditionInputModel = {
  claim: 'blueGroup',
  operator: 'CONTAINS',
  value: '\"test-bluegroup-saml\"',
};

// RuleInput
const ruleInputModel = {
  name: 'Manager group rule',
  expiration: 12,
  realm_name: 'https://idp.example.org/SAML2',
  conditions: [conditionInputModel],
};

// AssertionsActionControls
const assertionsActionControlsModel = {
  add: false,
};

// AssertionsInput
const assertionsInputModel = {
  rules: [ruleInputModel],
  action_controls: assertionsActionControlsModel,
};

// AccessActionControls
const accessActionControlsModel = {
  add: false,
};

// GroupActionControls
const groupActionControlsModel = {
  access: accessActionControlsModel,
};

// AccessGroupInput
const accessGroupInputModel = {
  name: 'IAM Admin Group 8',
  description: 'This access group template allows admin access to all IAM platform services in the account.',
  members: membersInputModel,
  assertions: assertionsInputModel,
  action_controls: groupActionControlsModel,
};

// PolicyTemplatesInput
const policyTemplatesInputModel = {
  id: testPolicyTemplateId,
  version: '1',
};

const params = {
  templateId: testTemplateId,
  name: 'IAM Admin Group template 2',
  description: 'This access group template allows admin access to all IAM platform services in the account.',
  group: accessGroupInputModel,
  policyTemplateReferences: [policyTemplatesInputModel],
};

let res;
try {
  res = await iamAccessGroupsService.createTemplateVersion(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

members_action_controls_model = {
  'add': True,
  'remove': False,
}

members_input_model = {
  'users': ['IBMid-50PJGPKYJJ', 'IBMid-665000T8WY'],
  'action_controls': members_action_controls_model,
}

condition_input_model = {
  'claim': 'blueGroup',
  'operator': 'CONTAINS',
  'value': '\"test-bluegroup-saml\"',
}

rule_input_model = {
  'name': 'Manager group rule',
  'expiration': 12,
  'realm_name': 'https://idp.example.org/SAML2',
  'conditions': [condition_input_model],
}

assertions_action_controls_model = {
  'add': False,
}

assertions_input_model = {
  'rules': [rule_input_model],
  'action_controls': assertions_action_controls_model,
}

access_action_controls_model = {
  'add': False,
}

group_action_controls_model = {
  'access': access_action_controls_model,
}

access_group_input_model = {
  'name': 'IAM Admin Group 8',
  'description': 'This access group template allows admin access to all IAM platform services in the account.',
  'members': members_input_model,
  'assertions': assertions_input_model,
  'action_controls': group_action_controls_model,
}

policy_templates_input_model = {
  'id': test_policy_template_id,
  'version': '1',
}

response = iam_access_groups_service.create_template_version(
  template_id=test_template_id,
  name='IAM Admin Group template 2',
  description='This access group template allows admin access to all IAM platform services in the account.',
  group=access_group_input_model,
  policy_template_references=[policy_templates_input_model],
)
create_template_version_response = response.get_result()

print(json.dumps(create_template_version_response, indent=2))
Copy to clipboard

Response

Response Body

TemplateVersionResponse

Response output for template

Introduction

Endpoint URLs

Authentication

Auditing

Error handling

Additional headers

Pagination

Sorting

Rate limiting

Related APIs

Methods

Create an access group

Authorization

Auditing

Request

Custom Headers

Transaction-Id

Query Parameters

account_id

Request Body

name

description

parameter

ctx

CreateAccessGroupOptions

AccountID

Name

Description

TransactionID

CreateAccessGroupOptions

accountId

name

description

transactionId

parameters

accountId

name

description

transactionId

parameters

account_id

name

description

transaction_id

Response

Response Body

id

name

description

account_id

created_at

created_by_id

last_modified_at

last_modified_by_id

href

is_federated

crn

Group

ID

Name

Description

AccountID

CreatedAt

CreatedByID

LastModifiedAt

LastModifiedByID

Href

IsFederated

CRN

Group

id

name

description

accountId

createdAt

createdById

lastModifiedAt

lastModifiedById

href

isFederated