User Management | IBM Cloud API Docs

Introduction

Last updated: 2022-11-04

With the User Management API, you can manage the users within your account, such as inviting, retrieving, updating, or removing users. You can also manage user profiles and settings. In addition to the account ID, this API uses the user's IAM ID. The IAM ID is a digital identity that is used to identify a user or service in IBM Cloud. SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

User Management is a platform service, which means that it uses platform management IAM roles to determine access permissions. For information about User Management roles, see Platform management roles in the IAM documentation.

User account status

A user can be in the following states.

Table 1. User states
State	Description
`ACTIVE`	An active user state.
`VPN_ONLY`	In this state, the user cannot log in through the IBM Cloud console.
`DISABLED_CLASSIC_INFRASTRUCTURE`	In this state, the user cannot access classic infrastructure (SoftLayer) resources.
`PROCESSING`	This state is a read-only system state.
`PENDING`	This state is a read only system state.
`SUSPENDED`	In this state, the user has a suspended account.
`ERROR_WHILE_PROCESSING`	This state is caused by an error while creating the user.
`ERROR_WHILE_DELETING`	This state is caused by an error during V3 delete of the user.
`IAMID_INVALID`	In this state, the IBMid of this user may no longer exist.

Users with the appropriate User Management IAM role can change a user between the ACTIVE, VPN_ONLY, and DISABLED_CLASSIC_INFRASTRUCTURE states. PROCESSING, PENDING, ERROR_WHILE_PROCESSING, ERROR_WHILE_DELETING, and IAMID_INVALID states are read-only system states that cannot be updated through the API.

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

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>user-management</artifactId>
    <version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:user-management:{version}'

View on GitHub

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

Installing the Go SDK

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

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

Go get

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

View on GitHub

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

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

Installation

npm install @ibm-cloud/platform-services

View on GitHub

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

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

Installation

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

View on GitHub

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

Endpoint URLs

The User Management API uses the following global endpoint URL for all regions. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://user-management.cloud.ibm.com

Virtual private cloud (VPC) based access requires a virtual private endpoint gateway (VPE gateway). For more information, see Creating an endpoint gateway.

Private endpoint URL for VPC infrastructure: https://private.user-management.cloud.ibm.com. VPE gateway creation is supported in following datacenters:
- Dallas
- Washington

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

Private endpoint URLs for classic infrastructure:
- Dallas: https://private.us-south.user-management.cloud.ibm.com
- Washington DC: https://private.us-east.user-management.cloud.ibm.com

Example API request

curl -X {request_method} "https://user-management.cloud.ibm.com/{method_endpoint}"

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

Authentication

Authorization to the user management 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 user management services. For information about how to obtain an IAM token for an authenticated user or service ID, see the IAM Identity Service API documentation.

Adequate access is required to use the API. Each method lists the IAM action that you need to be assigned access to. For more information about IAM actions and how they map to roles, see see Assigning access to account management services.

The User Management API does not cover user access. To manage user access, use the IAM Policy Management API and IAM Access Group API instead.

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

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

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

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

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

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

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

To retrieve your access token:

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

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

Example that sets options by using environment variables

export USER_MANAGEMENT_APIKEY=<API_KEY>

import {
    "github.com/IBM/platform-services-go-sdk/usermanagementv1"
}
...
userManagementServiceOptions := &usermanagementv1.UserManagementV1Options{}
userManagementService, err := usermanagementv1.NewUserManagementV1UsingExternalConfig(userManagementServiceOptions)

Replace <API_KEY> with your IBM Cloud IAM API key. Invoke service operations by using the userManagementService variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Example that sets options by using environment variables

export USER_MANAGEMENT_APIKEY=<API_KEY>

import com.ibm.cloud.platform_services.user_management.v1.UserManagement;
...
GlobalSearch userManagementService = UserManagement.newInstance();
Copy to clipboard

Replace <API_KEY> with your IBM Cloud IAM API key. Invoke service operations by using the userManagementService variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Example that sets options by using environment variables

export USER_MANAGEMENT_APIKEY=<API_KEY>

const UserManagementV1 = require('@ibm-cloud/platform-services/user-management/v1');
...
const userManagementService = UserManagementV1.newInstance({});
Copy to clipboard

Replace <API_KEY> with your IBM Cloud IAM API key. Invoke service operations by using the userManagementService variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Example that sets options by using environment variables

export USER_MANAGEMENT_APIKEY=<API_KEY>

from ibm_platform_services import UserManagementV1
...
user_management_service = UserManagementV1.new_instance()

Replace <API_KEY> with your IBM Cloud IAM API key. Invoke service operations by using the user_management_service variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Auditing

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

For more information about how to track activity in an enterprise, see Auditing events for account management.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 2xx response indicates success. A 4xx type response indicates a failure, and a 500 type response indicates an internal system error.

Table 2. Error codes
HTTP Error Code	Description	Recovery
`200`	Success	The request was successful.
`202`	Accepted	The request was accepted.
`204`	No Content	The request was successful. No response body is provided.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access '{namespace}'.
`404`	Not Found	The requested resource could not be found.
`500`	Internal Server Error	Your request could not be processed. Wait a few minutes and try again.

Retrieve users in the account. You can use the IAM service token or a user token for authorization. To use this method, the requesting user or service ID must have at least the viewer, editor, or administrator role on the User Management service. If unrestricted view is enabled, the user can see all users in the same account without an IAM role. If restricted view is enabled and user has the viewer, editor, or administrator role on the user management service, the API returns all users in the account. If unrestricted view is enabled and the user does not have these roles, the API returns only the current user. Users are returned in a paginated list with a default limit of 100 users. You can iterate through all users by following the next_url field. Additional substring search fields are supported to filter the users.

Retrieve users in the account. You can use the IAM service token or a user token for authorization. To use this method, the requesting user or service ID must have at least the viewer, editor, or administrator role on the User Management service. If unrestricted view is enabled, the user can see all users in the same account without an IAM role. If restricted view is enabled and user has the viewer, editor, or administrator role on the user management service, the API returns all users in the account. If unrestricted view is enabled and the user does not have these roles, the API returns only the current user. Users are returned in a paginated list with a default limit of 100 users. You can iterate through all users by following the next_url field.

GET /v2/accounts/{account_id}/users

(userManagement *UserManagementV1) ListUsers(listUsersOptions *ListUsersOptions) (result *UserList, response *core.DetailedResponse, err error)

(userManagement *UserManagementV1) ListUsersWithContext(ctx context.Context, listUsersOptions *ListUsersOptions) (result *UserList, response *core.DetailedResponse, err error)

ServiceCall<UserList> listUsers(ListUsersOptions listUsersOptions)
Copy to clipboard

listUsers(params)

list_users(self,
        account_id: str,
        *,
        limit: int = None,
        start: str = None,
        user_id: str = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

user-management.cloud-user.list

Auditing

Calling this method generates the following auditing event.

user-management.cloud-user.list

Request

Instantiate the ListUsersOptions struct and set the fields to provide parameter values for the ListUsers method.

Use the ListUsersOptions.Builder to create a ListUsersOptions object that contains the parameter values for the listUsers method.

Path Parameters

account_id
Required*
string
The account ID of the specified user.

Query Parameters

limit
integer
The number of results to be returned.

Possible values: value ≤ 100
Default: 100
include_settings
boolean
The user settings to be returned. Set to true to view language, allowed IP address, and authentication settings.
search
string
The desired search results to be returned. To view the list of users with the additional search filter, use the following query options: firstname, lastname, email, state, substate, iam_id, realm, and userId. HTML URL encoding for the search query and : must be used. For example, search=state%3AINVALID returns a list of invalid users. Multiple search queries can be combined to obtain OR results using , operator (not URL encoded). For example, search=state%3AINVALID,email%3Amail.test.ibm.com.
_start
string
An optional token that indicates the beginning of the page of results to be returned. If omitted, the first page of results is returned. This value is obtained from the 'next_url' field of the operation response.
user_id
string
Filter users based on their user ID.
email
string
Filter users based on their email address.
realm
string
Filter users based on realm. The realm identifies the provider of the user, such as IBMid or an external identity provider. For more information, see see Users

parameter

WithContext method only

ListUsersOptions

The ListUsers options.

ListUsersOptions

The listUsers options.

parameters

accountId
Required*
string
The account ID of the specified user.
limit
number
The number of results to be returned.

Possible values: value ≤ 100
start
string
An optional token that indicates the beginning of the page of results to be returned. If omitted, the first page of results is returned. This value is obtained from the 'next_url' field of the operation response.
userId
string
Filter users based on their user ID.

parameters

account_id
Required*
str
The account ID of the specified user.
limit
int
The number of results to be returned.

Possible values: value ≤ 100
start
str
An optional token that indicates the beginning of the page of results to be returned. If omitted, the first page of results is returned. This value is obtained from the 'next_url' field of the operation response.
user_id
str
Filter users based on their user ID.

Example request

curl -X GET   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users   -H 'Authorization: Bearer <IAM_TOKEN>'

Example request

listUsersOptions := &usermanagementv1.ListUsersOptions{
  AccountID: &accountID,
}

pager, err := userManagementService.NewUsersPager(listUsersOptions)
if err != nil {
  panic(err)
}

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

Example request

ListUsersOptions listUsersOptions = new ListUsersOptions.Builder()
  .accountId(accountId)
  .build();

UsersPager pager = new UsersPager(userManagementService, listUsersOptions);
List<UserProfile> allResults = new ArrayList<>();
while (pager.hasNext()) {
  List<UserProfile> nextPage = pager.getNext();
  allResults.addAll(nextPage);
}

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

Example request

const params = {
  accountId: accountId,
};

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

Example request

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

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

Response

Response Body

UserList

The users returned.

UserList

The users returned.

UserList

The users returned.

UserList

The users returned.

UserList

The users returned.

Status Code

200
Users were returned successfully.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
404
The resource could not be found.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "total_results": 1,
  "limit": 100,
  "first_url": "/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users",
  "resources": [
    {
      "id": "83699daa4a0d4647b6bef17f9f73c1234",
      "iam_id": "IBMid-1000000000",
      "realm": "IBMid",
      "user_id": "cloud_api_example@ibm.com",
      "firstname": "firstname",
      "lastname": "lastname",
      "state": "ACTIVE",
      "email": "cloud_api_example@ibm.com",
      "phonenumber": "1234567890",
      "altphonenumber": "1234567891",
      "photo": "https://32a7b.https.cdn.softlayer.net/8032A7B/dal05.objectstorage.softlayer.net/v1/AUTH_f2968d51-d955-4506-8fc5-7345a06eb123/bluemix-photos/",
      "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
      "added_on": "2019-02-13T00:56:59.266Z"
    }
  ]
}
Copy to clipboard

Success example

{
  "total_results": 1,
  "limit": 100,
  "first_url": "/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users",
  "resources": [
    {
      "id": "83699daa4a0d4647b6bef17f9f73c1234",
      "iam_id": "IBMid-1000000000",
      "realm": "IBMid",
      "user_id": "cloud_api_example@ibm.com",
      "firstname": "firstname",
      "lastname": "lastname",
      "state": "ACTIVE",
      "email": "cloud_api_example@ibm.com",
      "phonenumber": "1234567890",
      "altphonenumber": "1234567891",
      "photo": "https://32a7b.https.cdn.softlayer.net/8032A7B/dal05.objectstorage.softlayer.net/v1/AUTH_f2968d51-d955-4506-8fc5-7345a06eb123/bluemix-photos/",
      "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
      "added_on": "2019-02-13T00:56:59.266Z"
    }
  ]
}
Copy to clipboard

Invite users to the account. You must use a user token for authorization. Service IDs can't invite users to the account. To use this method, the requesting user must have the editor or administrator role on the User Management service. For more information, see the Inviting users documentation. You can specify the user account role and the corresponding IAM policy information in the request body.

When you invite a user to an account, the user is initially created in the PROCESSING state. After the user is successfully created, all specified permissions are configured, and the activation email is sent, the invited user is transitioned to the PENDING state. When the invited user clicks the activation email and creates and confirms their IBM Cloud account, the user is transitioned to ACTIVE state. If the user email is already verified, no email is generated.

POST /v2/accounts/{account_id}/users

(userManagement *UserManagementV1) InviteUsers(inviteUsersOptions *InviteUsersOptions) (result *InvitedUserList, response *core.DetailedResponse, err error)

(userManagement *UserManagementV1) InviteUsersWithContext(ctx context.Context, inviteUsersOptions *InviteUsersOptions) (result *InvitedUserList, response *core.DetailedResponse, err error)

ServiceCall<InvitedUserList> inviteUsers(InviteUsersOptions inviteUsersOptions)
Copy to clipboard

inviteUsers(params)

invite_users(self,
        account_id: str,
        *,
        users: List['InviteUser'] = None,
        iam_policy: List['InviteUserIamPolicy'] = None,
        access_groups: List[str] = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

user-management.user.create

Auditing

Calling this method generates the following auditing event.

user-management.user.create

Request

Instantiate the InviteUsersOptions struct and set the fields to provide parameter values for the InviteUsers method.

Use the InviteUsersOptions.Builder to create a InviteUsersOptions object that contains the parameter values for the inviteUsers method.

Path Parameters

account_id
Required*
string
The account ID of the specified user.

Request Body

ReqBodyInviteUser

Request body to invite a user.

parameter

WithContext method only

InviteUsersOptions

The InviteUsers options.

InviteUsersOptions

The inviteUsers options.

parameters

accountId
Required*
string
The account ID of the specified user.
users
A list of users to be invited.
iamPolicy
A list of IAM policies.
accessGroups
string[]
A list of access groups.

parameters

account_id
Required*
str
The account ID of the specified user.
users
A list of users to be invited.
iam_policy
A list of IAM policies.
access_groups
List[str]
A list of access groups.

Example request

curl -X POST   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users   -H 'Authorization: Bearer <IAM_TOKEN>'
  -H 'Content-Type: application/json'     -d '{
      "users": [
      {
        "email": "cloud_api_example_member@ibm.com",
        "account_role": "Member"
      }],
      "iam_policy": [{
        "type": "access",
        "roles": [{
          "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
        }],
        "resources": [{
          "attributes": [{
              "name": "accountId",
              "value": "987d4cfd77b04e9b9e1a6asdcc861234"
            },
            {
              "name": "resourceType",
              "value": "resource-group"
            },
            {
              "name": "resource",
              "value": "2c7449dd871049c29ec3a53853ce123e"
            }
          ]
        }]
      }],
      "access_groups":[
        "AccessGroupId-******-0f54-4d4f-89c2-e5fdc0b9a28c",
        "AccessGroupId-******-3087-4395-a382-a8e8ff9ccc23"
      ]
    }'
Copy to clipboard

Example request

inviteUserModel := &usermanagementv1.InviteUser{
  Email:       &memberEmail,
  AccountRole: core.StringPtr("Member"),
}

roleModel := &usermanagementv1.Role{
  RoleID: &viewerRoleID,
}

attributeModel := &usermanagementv1.Attribute{
  Name:  core.StringPtr("accountId"),
  Value: &accountID,
}

attributeModel2 := &usermanagementv1.Attribute{
  Name:  core.StringPtr("resourceGroupId"),
  Value: core.StringPtr("*"),
}

resourceModel := &usermanagementv1.Resource{
  Attributes: []usermanagementv1.Attribute{*attributeModel, *attributeModel2},
}

inviteUserIamPolicyModel := &usermanagementv1.InviteUserIamPolicy{
  Type:      core.StringPtr("access"),
  Roles:     []usermanagementv1.Role{*roleModel},
  Resources: []usermanagementv1.Resource{*resourceModel},
}

inviteUsersOptions := &usermanagementv1.InviteUsersOptions{
  AccountID:    &accountID,
  Users:        []usermanagementv1.InviteUser{*inviteUserModel},
  IamPolicy:    []usermanagementv1.InviteUserIamPolicy{*inviteUserIamPolicyModel},
  AccessGroups: []string{accessGroupID},
}

invitedUserList, response, err := userManagementAdminService.InviteUsers(inviteUsersOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(invitedUserList, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

InviteUser inviteUserModel = new InviteUser.Builder()
        .email(memberEmail)
        .accountRole("Member")
        .build();

Role roleModel = new Role.Builder()
        .roleId(viewerRoleId)
        .build();

Attribute attributeModel = new Attribute.Builder()
        .name("accountId")
        .value(accountId)
        .build();

Attribute attributeModel2 = new Attribute.Builder()
        .name("resourceGroupId")
        .value("*")
        .build();

Resource resourceModel = new Resource.Builder()
        .addAttributes(attributeModel)
        .addAttributes(attributeModel2)
        .build();

InviteUserIamPolicy inviteUserIamPolicyModel = new InviteUserIamPolicy.Builder()
        .type("access")
        .addRoles(roleModel)
        .addResources(resourceModel)
        .build();

InviteUsersOptions inviteUsersOptions = new InviteUsersOptions.Builder()
        .accountId(accountId)
        .addUsers(inviteUserModel)
        .addIamPolicy(inviteUserIamPolicyModel)
        .addAccessGroups(accessGroupId)
        .build();

Response<InvitedUserList> response = userManagementServiceAdmin.inviteUsers(inviteUsersOptions).execute();
InvitedUserList invitedUserList = response.getResult();

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

Example request

const inviteUserModel = {
  email: memberEmail,
  account_role: 'Member',
};

const roleModel = {
  role_id: viewerRoleId,
};

const attributeModel = {
  name: 'accountId',
  value: accountId,
};

const attributeModel2 = {
  name: 'resourceGroupId',
  value: '*',
};

const resourceModel = {
  attributes: [attributeModel, attributeModel2],
};

const inviteUserIamPolicyModel = {
  type: 'access',
  roles: [roleModel],
  resources: [resourceModel],
};

const params = {
  accountId: accountId,
  users: [inviteUserModel],
  iamPolicy: [inviteUserIamPolicyModel],
  accessGroups: [accessGroupId],
};

try {
  const res = await userManagementAdminService.inviteUsers(params);
  deleteUserId = res.result.resources[0].id;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

invite_user_model = {
  'email': member_email,
  'account_role': 'Member'
}

role_model = {'role_id': viewer_role_id}

attribute_model = {'name': 'accountId', 'value': account_id}

attribute_model2 = {'name': 'resourceGroupId', 'value': '*'}

resource_model = {'attributes': [attribute_model, attribute_model2]}

invite_user_iam_policy_model = {
  'type': 'access',
  'roles': [role_model],
  'resources': [resource_model]
}

invite_user_response = user_management_admin_service.invite_users(
  account_id=account_id,
  users=[invite_user_model],
  iam_policy=[invite_user_iam_policy_model],
  access_groups=[access_group_id]
).get_result()

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

Response

Response Body

InvitedUserList

A collection of invited users. This is the response returned by the invite_users operation.

InvitedUserList

A collection of invited users. This is the response returned by the invite_users operation.

InvitedUserList

A collection of invited users. This is the response returned by the invite_users operation.

InvitedUserList

A collection of invited users. This is the response returned by the invite_users operation.

InvitedUserList

A collection of invited users. This is the response returned by the invite_users operation.

Status Code

202
The user was successfully invited.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
404
The resource could not be found.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 202

{
  "resources": [
    {
      "id": "12000000000000000000000000000001",
      "email": "cloud_api_example_member@ibm.com",
      "state": "PROCESSING"
    }
  ]
}
Copy to clipboard

Success example

{
  "resources": [
    {
      "id": "12000000000000000000000000000001",
      "email": "cloud_api_example_member@ibm.com",
      "state": "PROCESSING"
    }
  ]
}
Copy to clipboard

Remove a user from an account by user ID or by email and realm. You must use a user token for authorization. Service IDs can't remove users from an account. The request must contain either the user ID or email in the query parameters. This method removes only a single user. If multiple users found for the given query, a bad request returns. The requesting user must have the editor or administrator role on the User Management service. For more information, see Removing users.

DELETE /v2/accounts/{account_id}/users

Authorization

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

user-management.user.delete

Auditing

Calling this method generates the following auditing event.

user-management.user.delete

Request

Path Parameters

account_id
Required*
string
The account ID of the specified user.

Query Parameters

user_id
Required*
string
The ID of the user that you want to remove from the account. Either user_id or email is required. To get the user_id of users in your account, list users.
email
Required*
string
The email address of the user that you want to remove. Either email or user_id is required.
realm
string
The realm of the user that you want to remove. The realm identifies the provider of the user, such as IBMid or an external identity provider. For more information, see Users

Example request

curl -X DELETE   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users?user_id=user%40ibm.com&email=user.email%40ibm.com&realm=ibmid   -H 'Authorization: Bearer <IAM_TOKEN>'   -H 'Content-Type: application/json'

Response

Status Code

204
The user was removed successfully.
400
The request has an invalid payload.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Retrieve a user's profile by the user's IAM ID in your account. You can use the IAM service token or a user token for authorization. To use this method, the requesting user or service ID must have at least the viewer, editor, or administrator role on the User Management service.

GET /v2/accounts/{account_id}/users/{iam_id}

(userManagement *UserManagementV1) GetUserProfile(getUserProfileOptions *GetUserProfileOptions) (result *UserProfile, response *core.DetailedResponse, err error)

(userManagement *UserManagementV1) GetUserProfileWithContext(ctx context.Context, getUserProfileOptions *GetUserProfileOptions) (result *UserProfile, response *core.DetailedResponse, err error)

ServiceCall<UserProfile> getUserProfile(GetUserProfileOptions getUserProfileOptions)
Copy to clipboard

getUserProfile(params)

get_user_profile(self,
        account_id: str,
        iam_id: str,
        *,
        include_activity: str = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

user-management.user.read

Auditing

Calling this method generates the following auditing event.

user-management.user.read

Request

Instantiate the GetUserProfileOptions struct and set the fields to provide parameter values for the GetUserProfile method.

Use the GetUserProfileOptions.Builder to create a GetUserProfileOptions object that contains the parameter values for the getUserProfile method.

Path Parameters

account_id
Required*
string
The account ID of the specified user.
iam_id
Required*
string
The user's IAM ID.

Query Parameters

include_activity
string
Include activity information of the user, such as the last authentication timestamp.

parameter

WithContext method only

GetUserProfileOptions

The GetUserProfile options.

GetUserProfileOptions

The getUserProfile options.

parameters

accountId
Required*
string
The account ID of the specified user.
iamId
Required*
string
The user's IAM ID.
includeActivity
string
Include activity information of the user, such as the last authentication timestamp.

parameters

account_id
Required*
str
The account ID of the specified user.
iam_id
Required*
str
The user's IAM ID.
include_activity
str
Include activity information of the user, such as the last authentication timestamp.

Example request

curl -X GET   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users/IBMid-1000000000   -H 'Authorization: Bearer <IAM_TOKEN>' \

Example request

getUserProfileOptions := userManagementService.NewGetUserProfileOptions(
  accountID,
  userID,
)

userProfile, response, err := userManagementService.GetUserProfile(getUserProfileOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(userProfile, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetUserProfileOptions getUserProfileOptions = new GetUserProfileOptions.Builder()
  .accountId(accountId)
  .iamId(userId)
  .build();

Response<UserProfile> response = userManagementService.getUserProfile(getUserProfileOptions).execute();
UserProfile userProfile = response.getResult();

System.out.println(userProfile);

Example request

const params = {
  accountId: accountId,
  iamId: userId,
};

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

Example request

user_profile = user_management_service.get_user_profile(
  account_id=account_id,
  iam_id=user_id,
).get_result()

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

Response

Response Body

UserProfile

Returned the user profile.

UserProfile

Returned the user profile.

UserProfile

Returned the user profile.

UserProfile

Returned the user profile.

UserProfile

Returned the user profile.

Status Code

200
The user was returned successfully.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
404
The resource could not be found.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "id": "83699daa4a0d4647b6bef17f9f73c1234",
  "iam_id": "IBMid-1000000000",
  "realm": "IBMid",
  "user_id": "cloud_api_example@ibm.com",
  "firstname": "firstname",
  "lastname": "lastname",
  "state": "ACTIVE",
  "email": "cloud_api_example@ibm.com",
  "phonenumber": "1234567890",
  "altphonenumber": "1234567891",
  "photo": "https://32a7b.https.cdn.softlayer.net/8032A7B/dal05.objectstorage.softlayer.net/v1/AUTH_f2968d51-d955-4506-8fc5-7345a06eb123/bluemix-photos/",
  "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
  "added_on": "2019-02-13T00:56:59.266Z"
}
Copy to clipboard

Success example

{
  "id": "83699daa4a0d4647b6bef17f9f73c1234",
  "iam_id": "IBMid-1000000000",
  "realm": "IBMid",
  "user_id": "cloud_api_example@ibm.com",
  "firstname": "firstname",
  "lastname": "lastname",
  "state": "ACTIVE",
  "email": "cloud_api_example@ibm.com",
  "phonenumber": "1234567890",
  "altphonenumber": "1234567891",
  "photo": "https://32a7b.https.cdn.softlayer.net/8032A7B/dal05.objectstorage.softlayer.net/v1/AUTH_f2968d51-d955-4506-8fc5-7345a06eb123/bluemix-photos/",
  "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
  "added_on": "2019-02-13T00:56:59.266Z"
}
Copy to clipboard

Partially update a user's profile by user's IAM ID. You can use the IAM service token or a user token for authorization. To use this method, the requesting user or service ID must have at least the editor or administrator role on the User Management service. A user or service ID with these roles can change a user's state between ACTIVE, VPN_ONLY, or DISABLED_CLASSIC_INFRASTRUCTURE, but they can't change the state to PROCESSING or PENDING because these are system states. For other request body fields, a user can update their own profile without having User Management service permissions.

PATCH /v2/accounts/{account_id}/users/{iam_id}

(userManagement *UserManagementV1) UpdateUserProfile(updateUserProfileOptions *UpdateUserProfileOptions) (response *core.DetailedResponse, err error)

(userManagement *UserManagementV1) UpdateUserProfileWithContext(ctx context.Context, updateUserProfileOptions *UpdateUserProfileOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> updateUserProfile(UpdateUserProfileOptions updateUserProfileOptions)
Copy to clipboard

updateUserProfile(params)

update_user_profile(self,
        account_id: str,
        iam_id: str,
        *,
        firstname: str = None,
        lastname: str = None,
        state: str = None,
        email: str = None,
        phonenumber: str = None,
        altphonenumber: str = None,
        photo: str = None,
        include_activity: str = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

user-management.user.update

Auditing

Calling this method generates the following auditing event.

user-management.user.update

Request

Instantiate the UpdateUserProfileOptions struct and set the fields to provide parameter values for the UpdateUserProfile method.

Use the UpdateUserProfileOptions.Builder to create a UpdateUserProfileOptions object that contains the parameter values for the updateUserProfile method.

Path Parameters

account_id
Required*
string
The account ID of the specified user.
iam_id
Required*
string
The user's IAM ID.

Query Parameters

include_activity
string
Include activity information of the user, such as the last authentication timestamp.

Request Body

ReqBodyUserProfilePatch

Request body to update a user profile.

parameter

WithContext method only

UpdateUserProfileOptions

The UpdateUserProfile options.

UpdateUserProfileOptions

The updateUserProfile options.

parameters

accountId
Required*
string
The account ID of the specified user.
iamId
Required*
string
The user's IAM ID.
firstname
string
The first name of the user.
lastname
string
The last name of the user.
state
string
The state of the user. Possible values are PROCESSING, PENDING, ACTIVE, DISABLED_CLASSIC_INFRASTRUCTURE, and VPN_ONLY.
email
string
The email address of the user.
phonenumber
string
The phone number of the user.
altphonenumber
string
The alternative phone number of the user.
photo
string
A link to a photo of the user.
includeActivity
string
Include activity information of the user, such as the last authentication timestamp.

parameters

account_id
Required*
str
The account ID of the specified user.
iam_id
Required*
str
The user's IAM ID.
firstname
str
The first name of the user.
lastname
str
The last name of the user.
state
str
The state of the user. Possible values are PROCESSING, PENDING, ACTIVE, DISABLED_CLASSIC_INFRASTRUCTURE, and VPN_ONLY.
email
str
The email address of the user.
phonenumber
str
The phone number of the user.
altphonenumber
str
The alternative phone number of the user.
photo
str
A link to a photo of the user.
include_activity
str
Include activity information of the user, such as the last authentication timestamp.

Example request

curl -X PATCH   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users/IBMid-1000000000   -H 'Authorization: Bearer <IAM_TOKEN>'   -H 'Content-Type: application/json'     -d '{
      "firstname": "TEST1"
    }'
Copy to clipboard

Example request

updateUserProfileOptions := userManagementService.NewUpdateUserProfileOptions(
  accountID,
  userID,
)
updateUserProfileOptions.SetPhonenumber("123456789")

response, err := userManagementService.UpdateUserProfile(updateUserProfileOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

UpdateUserProfileOptions updateUserProfileOptions = new UpdateUserProfileOptions.Builder()
  .accountId(accountId)
  .iamId(userId)
  .phonenumber("123456789")
  .build();

Response<Void> response = userManagementService.updateUserProfile(updateUserProfileOptions).execute();

Example request

const params = {
  accountId: accountId,
  iamId: userId,
  phonenumber: '123456789',
};

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

Example request

response = user_management_service.update_user_profile(
  account_id=account_id,
  iam_id=user_id,
  phonenumber='123456789',
).get_result()

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

Response

Status Code

204
The user profile was updated successfully.
400
The request has an invalid payload.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Remove users from an account by user's IAM ID. You must use a user token for authorization. Service IDs can't remove users from an account. To use this method, the requesting user must have the editor or administrator role on the User Management service. For more information, see the Removing users documentation.

DELETE /v2/accounts/{account_id}/users/{iam_id}

(userManagement *UserManagementV1) RemoveUser(removeUserOptions *RemoveUserOptions) (response *core.DetailedResponse, err error)

(userManagement *UserManagementV1) RemoveUserWithContext(ctx context.Context, removeUserOptions *RemoveUserOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> removeUser(RemoveUserOptions removeUserOptions)
Copy to clipboard

removeUser(params)

remove_user(self,
        account_id: str,
        iam_id: str,
        *,
        include_activity: str = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

user-management.user.delete

Auditing

Calling this method generates the following auditing event.

user-management.user.delete

Request

Instantiate the RemoveUserOptions struct and set the fields to provide parameter values for the RemoveUser method.

Use the RemoveUserOptions.Builder to create a RemoveUserOptions object that contains the parameter values for the removeUser method.

Path Parameters

account_id
Required*
string
The account ID of the specified user.
iam_id
Required*
string
The user's IAM ID.

Query Parameters

include_activity
string
Include activity information of the user, such as the last authentication timestamp.

parameter

WithContext method only

RemoveUserOptions

The RemoveUser options.

RemoveUserOptions

The removeUser options.

parameters

accountId
Required*
string
The account ID of the specified user.
iamId
Required*
string
The user's IAM ID.
includeActivity
string
Include activity information of the user, such as the last authentication timestamp.

parameters

account_id
Required*
str
The account ID of the specified user.
iam_id
Required*
str
The user's IAM ID.
include_activity
str
Include activity information of the user, such as the last authentication timestamp.

Example request

curl -X DELETE   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users/IBMid-1000000000   -H 'Authorization: Bearer <IAM_TOKEN>'   -H 'Content-Type: application/json'

Example request

removeUserOptions := userManagementService.NewRemoveUserOptions(
  accountID,
  deleteUserID,
)

response, err := userManagementAdminService.RemoveUser(removeUserOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

RemoveUserOptions removeUserOptions = new RemoveUserOptions.Builder()
  .accountId(accountId)
  .iamId(deleteUserId)
  .build();

Response<Void> response = userManagementService.removeUser(removeUserOptions).execute();

Example request

const params = {
  accountId: accountId,
  iamId: deleteUserId,
};

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

Example request

response = user_management_admin_service.remove_user(
  account_id=account_id,
  iam_id=delete_user_id,
).get_result()

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

Response

Status Code

204
The user was removed successfully.
400
The request has an invalid payload.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Accept a user invitation to an account. You can use the user's token for authorization. To use this method, the requesting user must provide the account ID for the account that they are accepting an invitation for. If the user already accepted the invitation request, it returns 204 with no response body.

POST /v2/users/accept

(userManagement *UserManagementV1) Accept(acceptOptions *AcceptOptions) (response *core.DetailedResponse, err error)

(userManagement *UserManagementV1) AcceptWithContext(ctx context.Context, acceptOptions *AcceptOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> accept(AcceptOptions acceptOptions)
Copy to clipboard

accept(params)

accept(self,
        *,
        account_id: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the AcceptOptions struct and set the fields to provide parameter values for the Accept method.

Use the AcceptOptions.Builder to create a AcceptOptions object that contains the parameter values for the accept method.

Request Body

ReqBodyAcceptUser

Request body to accept an invitation.

parameter

WithContext method only

AcceptOptions

The Accept options.

AcceptOptions

The accept options.

parameters

accountId
string

parameters

account_id
str

Example request

curl -X POST   https://user-management.cloud.ibm.com/v2/users/accept   -H 'Authorization: Bearer <IAM_TOKEN>'   -H 'Content-Type: application/json'     -d  '{
        "account_id": "<Account ID>"
      }'
Copy to clipboard

Response

Status Code

202
The request was accepted.
400
The request has an invalid payload.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Remove users from an account by using the user's IAM ID. You must use a user token for authorization. Service IDs can't remove users from an account. If removing the user fails it will set the user's state to ERROR_WHILE_DELETING. To use this method, the requesting user must have the editor or administrator role on the User Management service. For more information, see the Removing users documentation.

DELETE /v3/accounts/{account_id}/users/{iam_id}

(userManagement *UserManagementV1) V3RemoveUser(v3RemoveUserOptions *V3RemoveUserOptions) (response *core.DetailedResponse, err error)

(userManagement *UserManagementV1) V3RemoveUserWithContext(ctx context.Context, v3RemoveUserOptions *V3RemoveUserOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> v3RemoveUser(V3RemoveUserOptions v3RemoveUserOptions)
Copy to clipboard

v3RemoveUser(params)

v3_remove_user(self,
        account_id: str,
        iam_id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

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

user-management.user.delete

Auditing

Calling this method generates the following auditing event.

user-management.user.delete

Request

Instantiate the V3RemoveUserOptions struct and set the fields to provide parameter values for the V3RemoveUser method.

Use the V3RemoveUserOptions.Builder to create a V3RemoveUserOptions object that contains the parameter values for the v3RemoveUser method.

Path Parameters

account_id
Required*
string
The account ID of the specified user.
iam_id
Required*
string
The user's IAM ID.

parameter

WithContext method only

V3RemoveUserOptions

The V3RemoveUser options.

V3RemoveUserOptions

The v3RemoveUser options.

parameters

accountId
Required*
string
The account ID of the specified user.
iamId
Required*
string
The user's IAM ID.

parameters

account_id
Required*
str
The account ID of the specified user.
iam_id
Required*
str
The user's IAM ID.

Example request

curl -X DELETE   https://user-management.cloud.ibm.com/v3/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users/IBMid-1000000000   -H 'Authorization: Bearer <IAM_TOKEN>'   -H 'Content-Type: application/json'

Response

Status Code

202
The request was accepted.
400
The request has an invalid payload.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Bulk remove users from an account by specifying the users' IAM IDs. The API supports removing up to 50 users at a time. You must use a user token for authorization. Service IDs can't remove users from an account. If a partial failure occurs on deletion, the response is shown in the body. If removing any user fails, it will set the user's state to ERROR_WHILE_DELETING. To use this method, the requesting user must have the editor or administrator role on the User Management service. For more information, see Removing users documentation.

POST /v2/accounts/{account_id}/users_bulk_delete

Authorization

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

user-management.user.delete

Auditing

Calling this method generates the following auditing event.

user-management.user.bulk-delete

Request

Path Parameters

account_id
Required*
string
The account ID of the specified users.

Request Body

ReqBodyBulkUserRemove

Request body to bulk remove users.

Example request

curl -X POST   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users_bulk_delete   -H 'Authorization: Bearer <IAM_TOKEN>'   -H 'Content-Type: application/json'   -d '{ "users": ["IBMid-123456789", "IBMid-123409929"]}'
Copy to clipboard

Response

Response Body

ResBodyBulkUserRemove

Response to bulk remove users.

Status Code

207
There is a multiple status response. Check the response body.
400
The request has an invalid payload.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 207

{
  "account_id": "a99628bcfb2e40e7b7d6a70412412f",
  "users": [
    {
      "iam_id": "IBMid-06000260JS",
      "status_code": 204
    },
    {
      "iam_id": "IBMid-MPR1260JS",
      "trace": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "errors": [
        {
          "code": "error_occurred",
          "message": "Failed to delete the user"
        }
      ],
      "status_code": 503
    }
  ]
}
Copy to clipboard

Retrieve a user's settings by the user's IAM ID. You can use the IAM service token or a user token for authorization. To use this method, the requesting user or service ID must have the viewer, editor, or administrator role on the User Management service.

The user settings have several fields. The language field is the language setting for the user interface display language. The notification_language field is the language setting for phone and email notifications. The allowed_ip_addresses field specifies a list of IP addresses that the user can log in and perform operations from as described in Allowing specific IP addresses for a user. For information about the self_manage field, review information about the user-managed login setting.

GET /v2/accounts/{account_id}/users/{iam_id}/settings

(userManagement *UserManagementV1) GetUserSettings(getUserSettingsOptions *GetUserSettingsOptions) (result *UserSettings, response *core.DetailedResponse, err error)

(userManagement *UserManagementV1) GetUserSettingsWithContext(ctx context.Context, getUserSettingsOptions *GetUserSettingsOptions) (result *UserSettings, response *core.DetailedResponse, err error)

ServiceCall<UserSettings> getUserSettings(GetUserSettingsOptions getUserSettingsOptions)
Copy to clipboard

getUserSettings(params)

get_user_settings(self,
        account_id: str,
        iam_id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

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

user-management.user-setting.read

Auditing

Calling this method generates the following auditing event.

user-management.user-setting.read

Request

Instantiate the GetUserSettingsOptions struct and set the fields to provide parameter values for the GetUserSettings method.

Use the GetUserSettingsOptions.Builder to create a GetUserSettingsOptions object that contains the parameter values for the getUserSettings method.

Path Parameters

account_id
Required*
string
The account ID of the specified user.
iam_id
Required*
string
The user's IAM ID.

parameter

WithContext method only

GetUserSettingsOptions

The GetUserSettings options.

GetUserSettingsOptions

The getUserSettings options.

parameters

accountId
Required*
string
The account ID of the specified user.
iamId
Required*
string
The user's IAM ID.

parameters

account_id
Required*
str
The account ID of the specified user.
iam_id
Required*
str
The user's IAM ID.

Example request

curl -X GET   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users/IBMid-1000000000/settings   -H 'Authorization: Bearer <IAM_TOKEN>' \

Example request

getUserSettingsOptions := userManagementService.NewGetUserSettingsOptions(
  accountID,
  userID,
)

userSettings, response, err := userManagementService.GetUserSettings(getUserSettingsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(userSettings, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetUserSettingsOptions getUserSettingsOptions = new GetUserSettingsOptions.Builder()
  .accountId(accountId)
  .iamId(userId)
  .build();

Response<UserSettings> response = userManagementService.getUserSettings(getUserSettingsOptions).execute();
UserSettings userSettings = response.getResult();

System.out.println(userSettings);

Example request

const params = {
  accountId: accountId,
  iamId: userId,
};

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

Example request

user_settings = user_management_service.get_user_settings(
  account_id=account_id,
  iam_id=user_id,
).get_result()

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

Response

Response Body

UserSettings

The user settings returned.

UserSettings

The user settings returned.

UserSettings

The user settings returned.

UserSettings

The user settings returned.

UserSettings

The user settings returned.

Status Code

200
The user settings were retrieved successfully.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
404
The resource could not be found.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "language": "",
  "notification_language": "",
  "allowed_ip_addresses": "111.111.111.111",
  "self_manage": true
}
Copy to clipboard

Success example

{
  "language": "",
  "notification_language": "",
  "allowed_ip_addresses": "111.111.111.111",
  "self_manage": true
}
Copy to clipboard

Update a user's settings by the user's IAM ID. You can use the IAM service token or a user token for authorization. To fully use this method, the user or service ID must have the editor or administrator role on the User Management service. Without these roles, a user can update only their own language or notification_language fields. If self_manage is true, the user can also update the allowed_ip_addresses field.

PATCH /v2/accounts/{account_id}/users/{iam_id}/settings

(userManagement *UserManagementV1) UpdateUserSettings(updateUserSettingsOptions *UpdateUserSettingsOptions) (response *core.DetailedResponse, err error)

(userManagement *UserManagementV1) UpdateUserSettingsWithContext(ctx context.Context, updateUserSettingsOptions *UpdateUserSettingsOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> updateUserSettings(UpdateUserSettingsOptions updateUserSettingsOptions)
Copy to clipboard

updateUserSettings(params)

update_user_settings(self,
        account_id: str,
        iam_id: str,
        *,
        language: str = None,
        notification_language: str = None,
        allowed_ip_addresses: str = None,
        self_manage: bool = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

user-management.user-setting.update

Auditing

Calling this method generates the following auditing event.

user-management.user-setting.update

Request

Instantiate the UpdateUserSettingsOptions struct and set the fields to provide parameter values for the UpdateUserSettings method.

Use the UpdateUserSettingsOptions.Builder to create a UpdateUserSettingsOptions object that contains the parameter values for the updateUserSettings method.

Path Parameters

account_id
Required*
string
The account ID of the specified user.
iam_id
Required*
string
The user's IAM ID.

Request Body

UserSettings

The user settings returned.

parameter

WithContext method only

UpdateUserSettingsOptions

The UpdateUserSettings options.

UpdateUserSettingsOptions

The updateUserSettings options.

parameters

accountId
Required*
string
The account ID of the specified user.
iamId
Required*
string
The user's IAM ID.
language
string
The console UI language. By default, this field is empty.
notificationLanguage
string
The language for email and phone notifications. By default, this field is empty.
allowedIpAddresses
string
A comma-separated list of IP addresses.
Examples:
selfManage
boolean
Whether user managed login is enabled. The default value is false.

parameters

account_id
Required*
str
The account ID of the specified user.
iam_id
Required*
str
The user's IAM ID.
language
str
The console UI language. By default, this field is empty.
notification_language
str
The language for email and phone notifications. By default, this field is empty.
allowed_ip_addresses
str
A comma-separated list of IP addresses.
Examples:
self_manage
bool
Whether user managed login is enabled. The default value is false.

Example request

curl -X PATCH   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users/IBMid-1000000000/settings   -H 'Authorization: Bearer <IAM_TOKEN>'   -H 'Content-Type: application/json'     -d '{
      "language": "en-us"
    }'
Copy to clipboard

Example request

updateUserSettingsOptions := userManagementService.NewUpdateUserSettingsOptions(
  accountID,
  userID,
)
updateUserSettingsOptions.SetSelfManage(true)
updateUserSettingsOptions.SetAllowedIPAddresses("192.168.0.2,192.168.0.3")

response, err := userManagementService.UpdateUserSettings(updateUserSettingsOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

UpdateUserSettingsOptions updateUserSettingsOptions = new UpdateUserSettingsOptions.Builder()
  .accountId(accountId)
  .iamId(userId)
  .selfManage(true)
  .allowedIpAddresses("192.168.0.2,192.168.0.3")
  .build();

Response<Void> response = userManagementService.updateUserSettings(updateUserSettingsOptions).execute();
Copy to clipboard

Example request

const params = {
  accountId: accountId,
  iamId: userId,
  selfManage: true,
  allowedIpAddresses: '192.168.0.2,192.168.0.3',
};

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

Example request

response = user_management_service.update_user_settings(
  account_id=account_id,
  iam_id=user_id,
  self_manage=True,
  allowed_ip_addresses='192.168.0.2,192.168.0.3',
).get_result()

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

Response

Status Code

204
The user settings were updated successfully.
401
Your access token is not valid, or the authenication of your token failed.
403
Your access token is valid, but it does not have the necessary permissions to access this resource.
404
The resource could not be found.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Introduction

User account status

Endpoint URLs

Authentication

Auditing

Error handling

Methods

List users

Authorization

Auditing

Request

Path Parameters

account_id

Query Parameters

limit

include_settings

search

_start

user_id

email

realm

parameter

ctx

ListUsersOptions

AccountID

Limit

Start

UserID

ListUsersOptions

accountId

limit

start

userId

parameters

accountId

limit

start

userId

parameters

account_id

limit

start

user_id

Response

Response Body

total_results

limit

first_url

next_url

resources

UserList

TotalResults

Limit

FirstURL

NextURL

Resources

ID

IamID

Realm

UserID

Firstname

Lastname

State

Email

Phonenumber

Altphonenumber

Photo

AccountID

AddedOn

UserList

totalResults

limit

firstUrl

nextUrl

resources

id

iamId

realm

userId

firstname