Introduction

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

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

For more information, see Setting up access groups.

Example API request

curl -X {request_method} "{endpoint_url}/{method_endpoint}"

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

The code examples on this tab use the client library that is provided for Go.

Installation

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

GitHub

The code examples on this tab use the client library that is provided for Java.

Installation

Maven:

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>platform-services</artifactId>
    <version>X.X.X</version>
</dependency>

Gradle:

compile 'com.ibm.cloud:platform-services:X.X.X'

GitHub

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install ibm-platform-services

GitHub

The code examples on this tab use the client library that is provided for Python.

Installation

pip install --upgrade "ibm_platform_services>=X.X.X"

GitHub

Endpoint URL

The IAM Access Groups API uses the following 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/v2

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.

Authentication

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

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

Adequate permissions are required to use the Access Groups APIs. An IAM Administrator or Editor role on the 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.

Additional headers

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

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

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

Pagination

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

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

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

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

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

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

Sorting

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

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

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

Rate limiting

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

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

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

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

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

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

Methods

Create an Access Group

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

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

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

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

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

POST /groups
(iamAccessGroups *IamAccessGroupsV2) CreateAccessGroup(createAccessGroupOptions *CreateAccessGroupOptions) (result *Group, response *core.DetailedResponse, err error)
ServiceCall<Group> createAccessGroup(CreateAccessGroupOptions createAccessGroupOptions)
createAccessGroup(params, [callback()])
create_access_group(self, account_id: str, name: str, *, description: str = None, transaction_id: str = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

  • An optional transaction id for the request

Query Parameters

  • IBM Cloud account id under which the group is created

The Access Group to create

The CreateAccessGroup options.

The createAccessGroup options.

parameters

  • IBM Cloud account id under which the group is created.

  • Assign the specified name to the Access Group. This field has a limit of 100 characters.

  • Assign a description for the Access Group. This field has a limit of 250 characters.

  • An optional transaction id for the request.

parameters

  • IBM Cloud account id under which the group is created.

  • Assign the specified name to the Access Group. This field has a limit of 100 characters.

  • Assign a description for the Access Group. This field has a limit of 250 characters.

  • An optional transaction id for the request.

  • curl -X POST "{endpoint_url}/groups?account_id=$ACCOUNT_ID" -H "Authorization: $TOKEN" -H 'Content-Type: application/json' -d '{
      "name": "Awesome Developers",
      "description": "Group for awesome developers"
    }'

Response

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

Status Code

  • Group Created

  • Bad Request

  • Invalid Access Token

  • Access Denied

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "id": "ACCESS_GROUP_ID",
      "name": "Awesome Developers",
      "description": "Group for awesome developers",
      "account_id": "ACCOUNT_ID",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "CREATOR_ID"
    }
  • {
      "id": "ACCESS_GROUP_ID",
      "name": "Awesome Developers",
      "description": "Group for awesome developers",
      "account_id": "ACCOUNT_ID",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "CREATOR_ID"
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

List Access Groups

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

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

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

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

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

GET /groups
(iamAccessGroups *IamAccessGroupsV2) ListAccessGroups(listAccessGroupsOptions *ListAccessGroupsOptions) (result *GroupsList, response *core.DetailedResponse, err error)
ServiceCall<GroupsList> listAccessGroups(ListAccessGroupsOptions listAccessGroupsOptions)
listAccessGroups(params, [callback()])
list_access_groups(self, account_id: str, *, transaction_id: str = None, iam_id: str = None, limit: int = None, offset: int = None, sort: str = None, show_federated: bool = None, hide_public_access: bool = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

  • An optional transaction id for the request

Query Parameters

  • IBM Cloud account id under which the groups are listed

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

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

    Default: 50

  • Offset the results using this query parameter

    Default: 0

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

    Default: name

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

    Default: false

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

    Default: false

The ListAccessGroups options.

The listAccessGroups options.

parameters

  • IBM Cloud account id under which the groups are listed.

  • An optional transaction id for the request.

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

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

  • Offset the results using this query parameter.

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

    Default: name

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

    Default: false

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

    Default: false

parameters

  • IBM Cloud account id under which the groups are listed.

  • An optional transaction id for the request.

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

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

  • Offset the results using this query parameter.

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

    Default: name

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

    Default: false

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

    Default: false

  • curl -X GET "{endpoint_url}/groups?account_id=$ACCOUNT_ID" -H "Authorization: $TOKEN" -H 'Content-Type: application/json'

Response

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

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

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

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

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

Status Code

  • Success

  • Invalid Access Token

  • Access Denied

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "limit": 5,
      "offset": 0,
      "total_count": 20,
      "first": {
        "href": "{endpoint_url}/groups?limit=5&account_id=ACCOUNT_ID&show_federated=true"
      },
      "next": {
        "href": "{endpoint_url}/groups?offset=5&limit=5&account_id=ACCOUNT_ID&show_federated=true"
      },
      "last": {
        "href": "{endpoint_url}/groups?offset=15&limit=5&account_id=ACCOUNT_ID&show_federated=true"
      },
      "groups": [
        {
          "id": "AccessGroupId-PublicAccess",
          "name": "Public Access",
          "description": "This group includes all users and service IDs by default. All group members, including unauthenticated users, are given public access to any resources that are defined in the policies for the group.",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "CREATOR_ID",
          "href": "{endpoint_url}/groups/AccessGroupId-PublicAccess",
          "is_federated": false
        },
        {
          "id": "ACCESS_GROUP_ID",
          "name": "Group 1",
          "description": "Nate's description",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "LAST_MODIFIER_ID",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID",
          "is_federated": true
        },
        {
          "id": "ACCESS_GROUP_ID",
          "name": "Group 2",
          "description": "Nate's description",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "LAST_MODIFIER_ID",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID",
          "is_federated": true
        },
        {
          "id": "ACCESS_GROUP_ID",
          "name": "Group 3",
          "description": "Nate's description",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "LAST_MODIFIER_ID",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID",
          "is_federated": false
        },
        {
          "id": "ACCESS_GROUP_ID",
          "name": "Group 4",
          "description": "Nate's description",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "LAST_MODIFIER_ID",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID",
          "is_federated": false
        },
        {
          "id": "ACCESS_GROUP_ID",
          "name": "Group 5",
          "description": "Nate's description",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "LAST_MODIFIER_ID",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID",
          "is_federated": false
        }
      ]
    }
  • {
      "limit": 5,
      "offset": 0,
      "total_count": 20,
      "first": {
        "href": "{endpoint_url}/groups?limit=5&account_id=ACCOUNT_ID&show_federated=true"
      },
      "next": {
        "href": "{endpoint_url}/groups?offset=5&limit=5&account_id=ACCOUNT_ID&show_federated=true"
      },
      "last": {
        "href": "{endpoint_url}/groups?offset=15&limit=5&account_id=ACCOUNT_ID&show_federated=true"
      },
      "groups": [
        {
          "id": "AccessGroupId-PublicAccess",
          "name": "Public Access",
          "description": "This group includes all users and service IDs by default. All group members, including unauthenticated users, are given public access to any resources that are defined in the policies for the group.",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "CREATOR_ID",
          "href": "{endpoint_url}/groups/AccessGroupId-PublicAccess",
          "is_federated": false
        },
        {
          "id": "ACCESS_GROUP_ID",
          "name": "Group 1",
          "description": "Nate's description",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "LAST_MODIFIER_ID",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID",
          "is_federated": true
        },
        {
          "id": "ACCESS_GROUP_ID",
          "name": "Group 2",
          "description": "Nate's description",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "LAST_MODIFIER_ID",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID",
          "is_federated": true
        },
        {
          "id": "ACCESS_GROUP_ID",
          "name": "Group 3",
          "description": "Nate's description",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "LAST_MODIFIER_ID",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID",
          "is_federated": false
        },
        {
          "id": "ACCESS_GROUP_ID",
          "name": "Group 4",
          "description": "Nate's description",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "LAST_MODIFIER_ID",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID",
          "is_federated": false
        },
        {
          "id": "ACCESS_GROUP_ID",
          "name": "Group 5",
          "description": "Nate's description",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "last_modified_at": "2019-01-01T01:01:00Z",
          "last_modified_by_id": "LAST_MODIFIER_ID",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID",
          "is_federated": false
        }
      ]
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Get an Access Group

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

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

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

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

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

GET /groups/{access_group_id}
(iamAccessGroups *IamAccessGroupsV2) GetAccessGroup(getAccessGroupOptions *GetAccessGroupOptions) (result *Group, response *core.DetailedResponse, err error)
ServiceCall<Group> getAccessGroup(GetAccessGroupOptions getAccessGroupOptions)
getAccessGroup(params, [callback()])
get_access_group(self, access_group_id: str, *, transaction_id: str = None, show_federated: bool = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The Access Group to get

Query Parameters

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

    Default: false

The GetAccessGroup options.

The getAccessGroup options.

parameters

  • The Access Group to get.

  • An optional transaction id for the request.

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

    Default: false

parameters

  • The Access Group to get.

  • An optional transaction id for the request.

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

    Default: false

  • curl -X GET "{endpoint_url}/groups/$ACCESS_GROUP_ID" -H "Authorization: $TOKEN" -H 'Content-Type: application/json'

Response

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

Status Code

  • Get Successful

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "id": "ACCESS_GROUP_ID",
      "name": "Awesome Developers",
      "description": "Group for awesome developers",
      "account_id": "ACCOUNT_ID",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "is_federated": true
    }
  • {
      "id": "ACCESS_GROUP_ID",
      "name": "Awesome Developers",
      "description": "Group for awesome developers",
      "account_id": "ACCOUNT_ID",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID",
      "is_federated": true
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Update an Access Group

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

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

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

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

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

PATCH /groups/{access_group_id}
(iamAccessGroups *IamAccessGroupsV2) UpdateAccessGroup(updateAccessGroupOptions *UpdateAccessGroupOptions) (result *Group, response *core.DetailedResponse, err error)
ServiceCall<Group> updateAccessGroup(UpdateAccessGroupOptions updateAccessGroupOptions)
updateAccessGroup(params, [callback()])
update_access_group(self, access_group_id: str, if_match: str, *, name: str = None, description: str = None, transaction_id: str = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

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

  • An optional transaction id for the request

Path Parameters

  • The Access group to update

The Access group to update

The UpdateAccessGroup options.

The updateAccessGroup options.

parameters

  • The Access group to update.

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

  • Assign the specified name to the Access Group. This field has a limit of 100 characters.

  • Assign a description for the Access Group. This field has a limit of 250 characters.

  • An optional transaction id for the request.

parameters

  • The Access group to update.

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

  • Assign the specified name to the Access Group. This field has a limit of 100 characters.

  • Assign a description for the Access Group. This field has a limit of 250 characters.

  • An optional transaction id for the request.

  • curl -X PATCH "{endpoint_url}/groups/$ACCESS_GROUP_ID" -H "Authorization: $TOKEN" -H 'Content-Type: application/json' -H "If-Match: $ETAG" -d '{
      "name": "SUPER Awesome Developers",
      "description": "Group for SUPER awesome developers"
    }'

Response

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

An IAM access group.

Status Code

  • Group Updated

  • Bad Request

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Method Not Allowed

  • Precondition Failed

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "id": "ACCESS_GROUP_ID",
      "name": "SUPER Awesome Developers",
      "description": "Group for SUPER awesome developers",
      "account_id": "ACCOUNT_ID",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID"
    }
  • {
      "id": "ACCESS_GROUP_ID",
      "name": "SUPER Awesome Developers",
      "description": "Group for SUPER awesome developers",
      "account_id": "ACCOUNT_ID",
      "created_at": "2019-01-01T01:01:00Z",
      "created_by_id": "CREATOR_ID",
      "last_modified_at": "2019-01-01T01:01:00Z",
      "last_modified_by_id": "LAST_MODIFIER_ID"
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot update group for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot update group for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "incorrect_etag",
          "message": "If-Match header contains incorrect/invalid etag."
        }
      ],
      "status_code": 412
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "incorrect_etag",
          "message": "If-Match header contains incorrect/invalid etag."
        }
      ],
      "status_code": 412
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Delete an Access Group

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

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

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

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

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

DELETE /groups/{access_group_id}
(iamAccessGroups *IamAccessGroupsV2) DeleteAccessGroup(deleteAccessGroupOptions *DeleteAccessGroupOptions) (response *core.DetailedResponse, err error)
ServiceCall<Void> deleteAccessGroup(DeleteAccessGroupOptions deleteAccessGroupOptions)
deleteAccessGroup(params, [callback()])
delete_access_group(self, access_group_id: str, *, transaction_id: str = None, force: bool = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The Access group to delete

Query Parameters

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

    Default: false

The DeleteAccessGroup options.

The deleteAccessGroup options.

parameters

  • The Access group to delete.

  • An optional transaction id for the request.

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

    Default: false

parameters

  • The Access group to delete.

  • An optional transaction id for the request.

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

    Default: false

  • curl -X DELETE "{endpoint_url}/groups/$ACCESS_GROUP_ID" -H "Authorization: $TOKEN"

Response

Status Code

  • Delete Successful

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Method Not Allowed

  • Group Not Empty

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot delete group for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot delete group for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_empty",
          "message": "Access group is not empty: <id>"
        }
      ],
      "status_code": 409
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_empty",
          "message": "Access group is not empty: <id>"
        }
      ],
      "status_code": 409
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Add members to an Access Group

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

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

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

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

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

PUT /groups/{access_group_id}/members
(iamAccessGroups *IamAccessGroupsV2) AddMembersToAccessGroup(addMembersToAccessGroupOptions *AddMembersToAccessGroupOptions) (result *AddGroupMembersResponse, response *core.DetailedResponse, err error)
ServiceCall<AddGroupMembersResponse> addMembersToAccessGroup(AddMembersToAccessGroupOptions addMembersToAccessGroupOptions)
addMembersToAccessGroup(params, [callback()])
add_members_to_access_group(self, access_group_id: str, *, members: List['AddGroupMembersRequestMembersItem'] = None, transaction_id: str = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The Access Group to add the members to

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

The AddMembersToAccessGroup options.

The addMembersToAccessGroup options.

parameters

  • The Access Group to add the members to.

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

  • An optional transaction id for the request.

parameters

  • The Access Group to add the members to.

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

  • An optional transaction id for the request.

  • curl -X PUT "{endpoint_url}/groups/$ACCESS_GROUP_ID/members" -H "Authorization: $TOKEN" -H 'Content-Type: application/json' -d '{
      "members": [
        {
          "iam_id": "IBM_ID",
          "type": "user"
        },
        {
          "iam_id": "SERVICE_ID",
          "type": "service"
        }
      ]
    }'

Response

The members added to an access group.

The members added to an access group.

The members added to an access group.

The members added to an access group.

The members added to an access group.

Status Code

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

  • Bad Input (Including duplicate members in request)

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Method Not Allowed

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "members": [
        {
          "iam_id": "$IBM_ID",
          "type": "user",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "status_code": 200
        },
        {
          "iam_id": "$SERVICE_ID",
          "status_code": 400,
          "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
          "errors": [
            {
              "code": "error_occurred",
              "message": "The service id is missing or incorrect"
            }
          ]
        }
      ]
    }
  • {
      "members": [
        {
          "iam_id": "$IBM_ID",
          "type": "user",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID",
          "status_code": 200
        },
        {
          "iam_id": "$SERVICE_ID",
          "status_code": 400,
          "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
          "errors": [
            {
              "code": "error_occurred",
              "message": "The service id is missing or incorrect"
            }
          ]
        }
      ]
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "membership_not_found",
          "message": "Failed to find the membership"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "membership_not_found",
          "message": "Failed to find the membership"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot add members for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot add members for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

List Access Group members

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

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

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

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

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

GET /groups/{access_group_id}/members
(iamAccessGroups *IamAccessGroupsV2) ListAccessGroupMembers(listAccessGroupMembersOptions *ListAccessGroupMembersOptions) (result *GroupMembersList, response *core.DetailedResponse, err error)
ServiceCall<GroupMembersList> listAccessGroupMembers(ListAccessGroupMembersOptions listAccessGroupMembersOptions)
listAccessGroupMembers(params, [callback()])
list_access_group_members(self, access_group_id: str, *, transaction_id: str = None, limit: float = None, offset: float = None, type: str = None, verbose: bool = None, sort: str = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The access_group_id to list members of

Query Parameters

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

    Default: 50

  • Offset the results using this query parameter

    Default: 0

  • Filter the results by member type

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

    Default: false

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

The ListAccessGroupMembers options.

The listAccessGroupMembers options.

parameters

  • The access_group_id to list members of.

  • An optional transaction id for the request.

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

    Default: 50

  • Offset the results using this query parameter.

    Default: 0

  • Filter the results by member type.

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

    Default: false

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

parameters

  • The access_group_id to list members of.

  • An optional transaction id for the request.

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

    Default: 50

  • Offset the results using this query parameter.

    Default: 0

  • Filter the results by member type.

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

    Default: false

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

  • curl -X GET "{endpoint_url}/groups/$ACCESS_GROUP_ID/members?verbose=true" -H "Authorization: $TOKEN" -H 'Content-Type: application/json'

Response

The members of a group.

The members of a group.

The members of a group.

The members of a group.

The members of a group.

Status Code

  • Success

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "limit": 50,
      "offset": 0,
      "total_count": 2,
      "first": {
        "href": "{endpoint_url}/groups/ACCESS_GROUP_ID/members?limit=50&verbose=true"
      },
      "last": {
        "href": "{endpoint_url}/groups/ACCESS_GROUP_ID/members?offset=0&limit=50&verbose=true"
      },
      "members": [
        {
          "iam_id": "IBM_ID",
          "type": "user",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID/members/IAM_ID",
          "name": "John Doe",
          "email": "john.doe@ibm.com",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID"
        },
        {
          "iam_id": "SERVICE_ID",
          "type": "service",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID/members/SERVICE_ID",
          "name": "Service ID 1",
          "description": "This is the description of the service id",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID"
        }
      ]
    }
  • {
      "limit": 50,
      "offset": 0,
      "total_count": 2,
      "first": {
        "href": "{endpoint_url}/groups/ACCESS_GROUP_ID/members?limit=50&verbose=true"
      },
      "last": {
        "href": "{endpoint_url}/groups/ACCESS_GROUP_ID/members?offset=0&limit=50&verbose=true"
      },
      "members": [
        {
          "iam_id": "IBM_ID",
          "type": "user",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID/members/IAM_ID",
          "name": "John Doe",
          "email": "john.doe@ibm.com",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID"
        },
        {
          "iam_id": "SERVICE_ID",
          "type": "service",
          "href": "{endpoint_url}/groups/ACCESS_GROUP_ID/members/SERVICE_ID",
          "name": "Service ID 1",
          "description": "This is the description of the service id",
          "created_at": "2019-01-01T01:01:00Z",
          "created_by_id": "CREATOR_ID"
        }
      ]
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Check membership in an Access Group

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

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

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

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

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

HEAD /groups/{access_group_id}/members/{iam_id}
(iamAccessGroups *IamAccessGroupsV2) IsMemberOfAccessGroup(isMemberOfAccessGroupOptions *IsMemberOfAccessGroupOptions) (response *core.DetailedResponse, err error)
ServiceCall<Void> isMemberOfAccessGroup(IsMemberOfAccessGroupOptions isMemberOfAccessGroupOptions)
isMemberOfAccessGroup(params, [callback()])
is_member_of_access_group(self, access_group_id: str, iam_id: str, *, transaction_id: str = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The access_group_id to check for membership in

  • The iam_id to look for within the group

The IsMemberOfAccessGroup options.

The isMemberOfAccessGroup options.

parameters

  • The access_group_id to check for membership in.

  • The iam_id to look for within the group.

  • An optional transaction id for the request.

parameters

  • The access_group_id to check for membership in.

  • The iam_id to look for within the group.

  • An optional transaction id for the request.

  • curl -X HEAD "{endpoint_url}/groups/$ACCESS_GROUP_ID/members/$IAM_ID" -H "Authorization: $TOKEN"

Response

Status Code

  • Membership exists

  • Invalid Access Token

  • Access Denied

  • Membership not found

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Delete member from an Access Group

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

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.

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.

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.

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

DELETE /groups/{access_group_id}/members/{iam_id}
(iamAccessGroups *IamAccessGroupsV2) RemoveMemberFromAccessGroup(removeMemberFromAccessGroupOptions *RemoveMemberFromAccessGroupOptions) (response *core.DetailedResponse, err error)
ServiceCall<Void> removeMemberFromAccessGroup(RemoveMemberFromAccessGroupOptions removeMemberFromAccessGroupOptions)
removeMemberFromAccessGroup(params, [callback()])
remove_member_from_access_group(self, access_group_id: str, iam_id: str, *, transaction_id: str = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The access_group_id to find the membership in

  • The iam_id to remove from the group

The RemoveMemberFromAccessGroup options.

The removeMemberFromAccessGroup options.

parameters

  • The access_group_id to find the membership in.

  • The iam_id to remove from the group.

  • An optional transaction id for the request.

parameters

  • The access_group_id to find the membership in.

  • The iam_id to remove from the group.

  • An optional transaction id for the request.

  • curl -X DELETE "{endpoint_url}/groups/$ACCESS_GROUP_ID/members/$IAM_ID" -H "Authorization: $TOKEN"

Response

Status Code

  • Membership deleted

  • Invalid Access Token

  • Access Denied

  • Membership not found

  • Method Not Allowed

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "group_not_found",
          "message": "Failed to find the specified access group: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot delete group membership for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "method_not_allowed_for_group",
          "message": "Cannot delete group membership for: AccessGroupId-PublicAccess"
        }
      ],
      "status_code": 405
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Delete members from an Access Group

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

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.

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.

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.

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.

POST /groups/{access_group_id}/members/delete
(iamAccessGroups *IamAccessGroupsV2) RemoveMembersFromAccessGroup(removeMembersFromAccessGroupOptions *RemoveMembersFromAccessGroupOptions) (result *DeleteGroupBulkMembersResponse, response *core.DetailedResponse, err error)
ServiceCall<DeleteGroupBulkMembersResponse> removeMembersFromAccessGroup(RemoveMembersFromAccessGroupOptions removeMembersFromAccessGroupOptions)
removeMembersFromAccessGroup(params, [callback()])
remove_members_from_access_group(self, access_group_id: str, *, members: List[str] = None, transaction_id: str = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The access_group_id to find the memberships in

The members to remove from an access group.

The RemoveMembersFromAccessGroup options.

The removeMembersFromAccessGroup options.

parameters

  • The access_group_id to find the memberships in.

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

  • An optional transaction id for the request.

parameters

  • The access_group_id to find the memberships in.

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

  • An optional transaction id for the request.

  • curl -X POST "{endpoint_url}/groups/$ACCESS_GROUP_ID/members/delete" -H "Authorization: $TOKEN" -H 'Content-Type: application/json' -d '{ 
      "members": [
        "IBM_ID", 
        "SERVICE_ID" 
      ] 
    }'

Response

The access group id and the members removed from it.

The access group id and the members removed from it.

The access group id and the members removed from it.

The access group id and the members removed from it.

The access group id and the members removed from it.

Status Code

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

  • Bad Input (Including duplicate members in request)

  • Invalid Access Token

  • Access Denied

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "access_group_id": "ACCESS_GROUP_ID",
      "members": [
        {
          "iam_id": "IBM_ID",
          "status_code": 204
        },
        {
          "iam_id": "SERVICE_ID",
          "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
          "errors": [
            {
              "code": "error_occurred",
              "message": "Failed to find the membership"
            }
          ],
          "status_code": 404
        }
      ]
    }
  • {
      "access_group_id": "ACCESS_GROUP_ID",
      "members": [
        {
          "iam_id": "IBM_ID",
          "status_code": 204
        },
        {
          "iam_id": "SERVICE_ID",
          "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
          "errors": [
            {
              "code": "error_occurred",
              "message": "Failed to find the membership"
            }
          ],
          "status_code": 404
        }
      ]
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_payload",
          "message": "Payload contains invalid/missing data."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Delete member from all Access Groups

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

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

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

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

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

DELETE /groups/_allgroups/members/{iam_id}
(iamAccessGroups *IamAccessGroupsV2) RemoveMemberFromAllAccessGroups(removeMemberFromAllAccessGroupsOptions *RemoveMemberFromAllAccessGroupsOptions) (result *DeleteFromAllGroupsResponse, response *core.DetailedResponse, err error)
ServiceCall<DeleteFromAllGroupsResponse> removeMemberFromAllAccessGroups(RemoveMemberFromAllAccessGroupsOptions removeMemberFromAllAccessGroupsOptions)
removeMemberFromAllAccessGroups(params, [callback()])
remove_member_from_all_access_groups(self, account_id: str, iam_id: str, *, transaction_id: str = None, **kwargs) -> DetailedResponse

Request

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

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

Custom Headers

  • An optional transaction id for the request

Path Parameters

  • The iam_id to remove from all groups

Query Parameters

  • IBM Cloud account id for the group membership deletion

The RemoveMemberFromAllAccessGroups options.

The removeMemberFromAllAccessGroups options.

parameters

  • IBM Cloud account id for the group membership deletion.

  • The iam_id to remove from all groups.

  • An optional transaction id for the request.

parameters

  • IBM Cloud account id for the group membership deletion.

  • The iam_id to remove from all groups.

  • An optional transaction id for the request.

  • curl -X DELETE "{endpoint_url}/groups/_allgroups/members/$IAM_ID?account_id=$ACCOUNT_ID" -H "Authorization: $TOKEN"

Response

The response from the delete member from access groups request.

The response from the delete member from access groups request.

The response from the delete member from access groups request.

The response from the delete member from access groups request.

The response from the delete member from access groups request.

Status Code

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

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "iam_id": "some-member-id1",
      "groups": [
        {
          "access_group_id": "some-group-id1",
          "status_code": 204
        },
        {
          "access_group_id": "some-group-id2",
          "status_code": 409,
          "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
          "errors": [
            {
              "code": "error_occurred",
              "message": "Cloudant document update conflict occurred"
            }
          ]
        }
      ]
    }
  • {
      "iam_id": "some-member-id1",
      "groups": [
        {
          "access_group_id": "some-group-id1",
          "status_code": 204
        },
        {
          "access_group_id": "some-group-id2",
          "status_code": 409,
          "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
          "errors": [
            {
              "code": "error_occurred",
              "message": "Cloudant document update conflict occurred"
            }
          ]
        }
      ]
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "forbidden",
          "message": "Forbidden: You don't have the required access to complete this action. Contact your account owner for access"
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "no_groups_found",
          "message": "No groups found for member: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "no_groups_found",
          "message": "No groups found for member: <id>"
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Add member to multiple Access Groups

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.

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.

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.

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.

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 /groups/_allgroups/members/{iam_id}
(iamAccessGroups *IamAccessGroupsV2) AddMemberToMultipleAccessGroups(addMemberToMultipleAccessGroupsOptions *AddMemberToMultipleAccessGroupsOptions) (result *AddMembershipMultipleGroupsResponse, response *core.DetailedResponse, err error)
ServiceCall<AddMembershipMultipleGroupsResponse> addMemberToMultipleAccessGroups(AddMemberToMultipleAccessGroupsOptions addMemberToMultipleAccessGroupsOptions)
addMemberToMultipleAccessGroups(params, [callback()])
add_member_to_multiple_access_groups(self, account_id: str, iam_id: str, *, type: str = None, groups: List[str] = None, transaction_id: str = None, **kwargs) -> DetailedResponse

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

  • An optional transaction id for the request

Path Parameters

  • The iam_id to be added to the groups

Query Parameters

  • IBM Cloud account id of the groups that the member will be added to

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

The AddMemberToMultipleAccessGroups options.

The addMemberToMultipleAccessGroups options.

parameters

  • IBM Cloud account id of the groups that the member will be added to.

  • The iam_id to be added to the groups.

  • The type of the member, must be either "user" or "service".

  • The ids of the access groups a given member is to be added to.

  • An optional transaction id for the request.

parameters

  • IBM Cloud account id of the groups that the member will be added to.

  • The iam_id to be added to the groups.

  • The type of the member, must be either "user" or "service".

  • The ids of the access groups a given member is to be added to.

  • An optional transaction id for the request.

  • curl -X PUT "{endpoint_url}/groups/_allgroups/members/$IAM_ID?account_id=$ACCOUNT_ID" -H "Authorization: $TOKEN" -H 'Content-Type: application/json' -d '{
      "type": "user",
      "groups": [ "ACCESS_GROUP_ID1", "ACCESS_GROUP_ID2", "ACCESS_GROUP_ID3" ]
    }'

Response

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

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

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

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

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

Status Code

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

  • Bad Input (Including duplicate groups in request)

  • Invalid Access Token

  • Internal Server Error

  • Service Unavailable

Example responses
  • {
      "groups": [
        {
          "access_group_id": "ACCESS_GROUP_ID1",
          "status_code": 200
        },
        {
          "access_group_id": "ACCESS_GROUP_ID2",
          "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
          "errors": [
            {
              "code": "error_occurred",
              "message": "Group not found in account"
            }
          ],
          "status_code": 404
        },
        {
          "access_group_id": "ACCESS_GROUP_ID3",
          "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
        }
      ]
    }
  • {
      "groups": [
        {
          "access_group_id": "ACCESS_GROUP_ID1",
          "status_code": 200
        },
        {
          "access_group_id": "ACCESS_GROUP_ID2",
          "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
          "errors": [
            {
              "code": "error_occurred",
              "message": "Group not found in account"
            }
          ],
          "status_code": 404
        },
        {
          "access_group_id": "ACCESS_GROUP_ID3",
          "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
        }
      ]
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "duplicate_groupid_error",
          "message": "A duplicate groupId entry was found for ACCESS_GROUP_ID1. Please remove any duplicate entries."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "duplicate_groupid_error",
          "message": "A duplicate groupId entry was found for ACCESS_GROUP_ID1. Please remove any duplicate entries."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "invalid_token",
          "message": "The token is either missing or invalid"
        }
      ],
      "status_code": 401
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "internal_server_error",
          "message": "Internal Server Error"
        }
      ],
      "status_code": 500
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }
  • {
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "service_unavailable",
          "message": "Service Temporarily Unavailable"
        }
      ],
      "status_code": 503
    }

Create rule for an Access Group

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

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

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 /groups/{access_group_id}/rules
(iamAccessGroups *IamAccessGroupsV2) AddAccessGroupRule(addAccessGroupRuleOptions *AddAccessGroupRuleOptions) (result *Rule, response *core.DetailedResponse, err error)
ServiceCall<Rule> addAccessGroupRule(AddAccessGroupRuleOptions addAccessGroupRuleOptions)
addAccessGroupRule(params, [callback()])
add_access_group_rule(self, access_group_id: str, expiration: int, realm_name: str, conditions: List['RuleConditions'], *, name: str = None, transaction_id: str = None, **kwargs) -> DetailedResponse

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

  • An optional transaction id for the request

Path Parameters

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

A new rule to add to an access group.

The AddAccessGroupRule options.

The addAccessGroupRule options.

parameters

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

  • The number of hours that the rule lives for (Must be between 1 and 24).

  • The url of the identity provider.

  • A list of conditions the rule must satisfy.

  • The name of the rule.

  • An optional transaction id for the request.

parameters

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

  • The number of hours that the rule lives for (Must be between 1 and 24).

  • The url of the identity provider.

  • A list of conditions the rule must satisfy.

  • The name of the rule.

  • An optional transaction id for the request.

  • curl -X POST "{endpoint_url}/groups/$ACCESS_GROUP_ID/rules" -H "Authorization: $TOKEN" -H 'Content-Type: application/json' -d '{ 
      "name": "test rule name", 
      "expiration": 24, 
      "realm_name": "test-idp.com", 
      "conditions": [
        { 
          "claim": "blueGroups", 
          "operator": "CONTAINS", 
          "value": "\"test-bluegroup-saml\""  
        } 
      ] 
    }'

Response

A rule of an access group.

A rule of an access group.

A rule of an access group.

A rule of an access group.

A rule of an access group.