Introduction

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.

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.

Users with the appropriate User Management IAM role can change a user between the ACTIVE, VPN_ONLY, and DISABLED_CLASSIC_INFRASTRUCTURE states. PROCESSING and PENDING 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>platform-services</artifactId>
    <version>${version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:platform-services:${version}'

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-java-sdk

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

For more installation options, view this project in 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-platform-services

For more installation options, view this project in 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"

For more installation options, view this project in 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

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

  • Private endpoint URL for VPC infrastructure: https://private.user-management.cloud.ibm.com
  • 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.

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.

To retrieve your access token:

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

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

Example that sets client options programmatically

import com.ibm.cloud.sdk.core.security.Authenticator;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;
import com.ibm.cloud.platform_services.platform_services.user_management.v1.UserManagement;

// Create an IAM authenticator
Authenticator authenticator = new IamAuthenticator("{api_key}");

// Construct the service client
UserManagement service = new UserManagement(authenticator);

// Set the service URL
service.setServiceUrl("https://user-management.cloud.ibm.com");

Example that sets options by using environment variables

export USER_MANAGEMENT_URL=https://user-management.cloud.ibm.com
export USER_MANAGEMENT_AUTH_TYPE=iam
export USER_MANAGEMENT_APIKEY={api_key}
import com.ibm.cloud.platform_services.user_management.v1.UserManagement;

UserManagement service = UserManagement.newInstance();

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the service variable.

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

Example that sets client options programmatically

import {
    "github.com/IBM/go-sdk-core/v4/core"
    "github.com/IBM/platform-services-go-sdk/usermanagementv1"
}

// Create an IAM authenticator
authenticator := &core.IamAuthenticator{
    ApiKey: "{api_key}",
}

// Create a service options struct
options := &usermanagementv1.UserManagementV1Options{
    Authenticator: authenticator,                              
    URL:           "https://user-management.cloud.ibm.com",
}

// Construct the service client
service, err := usermanagementv1.NewUserManagementV1(options)
if err != nil {
    panic(err)
}

Example that sets options by using environment variables

export USER_MANAGEMENT_URL=https://user-management.cloud.ibm.com
export USER_MANAGEMENT_AUTH_TYPE=iam
export USER_MANAGEMENT_APIKEY={api_key}
service, err := usermanagementv1.NewUserManagementV1UsingExternalConfig(
        &usermanagementv1.UserManagementV1Options{})
if err != nil {
    panic(err)
}

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the service variable.

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

Example that sets client options programmatically

from ibm_platform_services import UserManagementV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Create an IAM authenticator
authenticator = IAMAuthenticator('{api_key}')

# Construct the service client
service =  UserManagementV1(authenticator=authenticator)

# Set the service URL
service.set_service_url('https://user-management.cloud.ibm.com')

Example that sets options by using environment variables

export USER_MANAGEMENT_URL=https://user-management.cloud.ibm.com
export USER_MANAGEMENT_AUTH_TYPE=iam
export USER_MANAGEMENT_APIKEY={api_key}
from ibm_platform_services import  UserManagementV1
service =  UserManagementV1.new_instance()

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the service variable.

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

Example that sets client options programmatically

const UserManagementV1 = require('ibm-platform-services/user-management/v1');
const { IamAuthenticator } = require('ibm-platform-services/auth');

// Create an IAM authenticator
const authenticator = new IamAuthenticator({
  apikey: '{api_key}',
});

// Construct the service client
const service = new UserManagementV1({
  authenticator,                                          
  serviceUrl: 'https://user-management.cloud.ibm.com', 
});

Example that sets options by using environment variables

export USER_MANAGEMENT_URL=https://user-management.cloud.ibm.com
export USER_MANAGEMENT_AUTH_TYPE=iam
export USER_MANAGEMENT_APIKEY={api_key}
const UserManagementV1 = require('ibm-platform-services/user-management/v1');

const service = UserManagementV1.newInstance();

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the service variable.

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

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.

Methods

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

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.

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.

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.

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)
listUsers(params)
list_users(self,
        account_id: str,
        *,
        state: str = None,
        limit: int = None,
        start: str = None,
        **kwargs
    ) -> DetailedResponse

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

  • The account ID of the specified user.

Query Parameters

  • The account status of the user.

  • The number of results to be returned.

    Constraints: value ≤ 100

    Default: 100

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

WithContext method only

The ListUsers options.

The listUsers options.

parameters

  • The account ID.

  • The state of the user.

  • The number of results to be returned.

    Constraints: value ≤ 100

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

parameters

  • The account ID.

  • The state of the user.

  • The number of results to be returned.

    Constraints: value ≤ 100

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

  • curl -X GET   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users   -H 'Authorization: Bearer <IAM_TOKEN>'
  • listUsersOptions := userManagementService.NewListUsersOptions(
      accountID,
    )
    listUsersOptions.SetState("ACTIVE")
    listUsersOptions.SetLimit(100)
    
    userList, response, err := userManagementService.ListUsers(listUsersOptions)
    if err != nil {
      panic(err)
    }
    b, _ := json.MarshalIndent(userList, "", "  ")
    fmt.Println(string(b))
  • ListUsersOptions listUsersOptions = new ListUsersOptions.Builder()
      .accountId(accountId)
      .state("ACTIVE")
      .limit(100)
      .build();
    
    Response<UserList> response = service.listUsers(listUsersOptions).execute();
    UserList userList = response.getResult();
    
    System.out.println(userList);
  • const params = {
      accountId: accountId,
      state: 'ACTIVE',
      limit: 100,
    };
    
    userManagementService.listUsers(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • user_list = user_management_service.list_users(
      account_id=account_id,
      state='ACTIVE',
      limit=100,
    ).get_result()
    
    print(json.dumps(user_list, indent=2))

Response

The users returned.

The users returned.

The users returned.

The users returned.

The users returned.

Status Code

  • Users were returned successfully.

  • Your access token is not valid, or the authenication of your token failed.

  • Your access token is valid, but it does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • 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
  • {
      "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"
        }
      ]
    }
  • {
      "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"
        }
      ]
    }

Invite users to an account

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.

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.

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.

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.

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)
inviteUsers(params)
invite_users(self,
        account_id: str,
        *,
        users: List['InviteUser'] = None,
        iam_policy: List['InviteUserIamPolicy'] = None,
        access_groups: List[str] = None,
        **kwargs
    ) -> DetailedResponse

Authorization

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

  • 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

  • The account ID of the specified user.

Request body to invite a user.

WithContext method only

The InviteUsers options.

The inviteUsers options.

parameters

  • The account ID.

  • A list of users to be invited.

  • A list of IAM policies.

  • A list of access groups.

parameters

  • The account ID.

  • A list of users to be invited.

  • A list of IAM policies.

  • A list of access groups.

  • 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"
          ]
        }'
  • 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))
  • 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 = adminService.inviteUsers(inviteUsersOptions).execute();
    InvitedUserList invitedUserList = response.getResult();
    
    System.out.println(invitedUserList);
  • 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],
    };
    
    userManagementAdminService.inviteUsers(params)
      .then(res => {
        deleteUserId = res.result.resources[0].id;
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • 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))

Response

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

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

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

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

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

Status Code

  • The user was successfully invited.

  • Your access token is not valid, or the authenication of your token failed.

  • Your access token is valid, but it does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • 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
  • {
      "resources": [
        {
          "id": "12000000000000000000000000000001",
          "email": "cloud_api_example_member@ibm.com",
          "state": "PROCESSING"
        }
      ]
    }
  • {
      "resources": [
        {
          "id": "12000000000000000000000000000001",
          "email": "cloud_api_example_member@ibm.com",
          "state": "PROCESSING"
        }
      ]
    }

Get user profile

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.

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.

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.

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.

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)
getUserProfile(params)
get_user_profile(self,
        account_id: str,
        iam_id: str,
        **kwargs
    ) -> DetailedResponse

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

  • The account ID of the specified user.

  • The user's IAM ID.

WithContext method only

The GetUserProfile options.

The getUserProfile options.

parameters

  • The account ID.

  • The user's IAM ID.

parameters

  • The account ID.

  • The user's IAM ID.

  • curl -X GET   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users/IBMid-1000000000   -H 'Authorization: Bearer <IAM_TOKEN>' \
  • getUserProfileOptions := userManagementService.NewGetUserProfileOptions(
      accountID,
      userID,
    )
    
    userProfile, response, err := userManagementService.GetUserProfile(getUserProfileOptions)
    if err != nil {
      panic(err)
    }
    b, _ := json.MarshalIndent(userProfile, "", "  ")
    fmt.Println(string(b))
  • GetUserProfileOptions getUserProfileOptions = new GetUserProfileOptions.Builder()
      .accountId(accountId)
      .iamId(userId)
      .build();
    
    Response<UserProfile> response = service.getUserProfile(getUserProfileOptions).execute();
    UserProfile userProfile = response.getResult();
    
    System.out.println(userProfile);
  • const params = {
      accountId: accountId,
      iamId: userId,
    };
    
    userManagementService.getUserProfile(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • 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

Returned the user profile.

Returned the user profile.

Returned the user profile.

Returned the user profile.

Returned the user profile.

Status Code

  • The user was returned successfully.

  • Your access token is not valid, or the authenication of your token failed.

  • Your access token is valid, but it does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • 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
  • {
      "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"
    }
  • {
      "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"
    }

Partially update user profile

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.

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.

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.

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.

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)
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,
        **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 > name > Access policies.

  • 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

  • The account ID of the specified user.

  • The user's IAM ID.

Request body to update a user profile.

WithContext method only

The UpdateUserProfile options.

The updateUserProfile options.

parameters

  • The account ID.

  • The user's IAM ID.

  • The first name of the user.

  • The last name of the user.

  • The state of the user. Possible values are PROCESSING, PENDING, ACTIVE, DISABLED_CLASSIC_INFRASTRUCTURE, and VPN_ONLY.

  • The email address of the user.

  • The phone number of the user.

  • The alternative phone number of the user.

  • A link to a photo of the user.

parameters

  • The account ID.

  • The user's IAM ID.

  • The first name of the user.

  • The last name of the user.

  • The state of the user. Possible values are PROCESSING, PENDING, ACTIVE, DISABLED_CLASSIC_INFRASTRUCTURE, and VPN_ONLY.

  • The email address of the user.

  • The phone number of the user.

  • The alternative phone number of the user.

  • A link to a photo of the user.

  • 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"
        }'
  • updateUserProfileOptions := userManagementService.NewUpdateUserProfileOptions(
      accountID,
      userID,
    )
    updateUserProfileOptions.SetPhonenumber("123456789")
    
    response, err := userManagementService.UpdateUserProfile(updateUserProfileOptions)
    if err != nil {
      panic(err)
    }
  • UpdateUserProfileOptions updateUserProfileOptions = new UpdateUserProfileOptions.Builder()
      .accountId(accountId)
      .iamId(userId)
      .phonenumber("123456789")
      .build();
    
    service.updateUserProfile(updateUserProfileOptions).execute();
  • const params = {
      accountId: accountId,
      iamId: userId,
      phonenumber: '123456789',
    };
    
    userManagementService.updateUserProfile(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • 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))

Response

Status Code

  • The user profile was updated successfully.

  • The request has an invalid payload.

  • Your access token is not valid, or the authenication of your token failed.

  • Your access token is valid, but it does not have the necessary permissions to access this resource.

  • 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 user from account

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.

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.

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.

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.

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)
removeUser(params)
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 > name > Access policies.

  • 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

  • The account ID of the specified user.

  • The user's IAM ID.

WithContext method only

The RemoveUser options.

The removeUser options.

parameters

  • The account ID.

  • The user's IAM ID.

parameters

  • The account ID.

  • The user's IAM ID.

  • 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'
  • removeUserOptions := userManagementService.NewRemoveUserOptions(
      accountID,
      deleteUserID,
    )
    
    response, err := userManagementAdminService.RemoveUser(removeUserOptions)
    if err != nil {
      panic(err)
    }
  • RemoveUserOptions removeUserOptions = new RemoveUserOptions.Builder()
      .accountId(accountId)
      .iamId(deleteUserId)
      .build();
    
    service.removeUser(removeUserOptions).execute();
  • const params = {
      accountId: accountId,
      iamId: deleteUserId,
    };
    
    userManagementAdminService.removeUser(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • 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

  • The user was removed successfully.

  • The request has an invalid payload.

  • Your access token is not valid, or the authenication of your token failed.

  • Your access token is valid, but it does not have the necessary permissions to access this resource.

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

Get user settings

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.

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.

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.

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.

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)
getUserSettings(params)
get_user_settings(self,
        account_id: str,
        iam_id: str,
        **kwargs
    ) -> DetailedResponse

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

  • The account ID of the specified user.

  • The user's IAM ID.

WithContext method only

The GetUserSettings options.

The getUserSettings options.

parameters

  • The account ID.

  • The user's IAM ID.

parameters

  • The account ID.

  • The user's IAM ID.

  • curl -X GET   https://user-management.cloud.ibm.com/v2/accounts/987d4cfd77b04e9b9e1a6asdcc861234/users/IBMid-1000000000/settings   -H 'Authorization: Bearer <IAM_TOKEN>' \
  • getUserSettingsOptions := userManagementService.NewGetUserSettingsOptions(
      accountID,
      userID,
    )
    
    userSettings, response, err := userManagementService.GetUserSettings(getUserSettingsOptions)
    if err != nil {
      panic(err)
    }
    b, _ := json.MarshalIndent(userSettings, "", "  ")
    fmt.Println(string(b))
  • GetUserSettingsOptions getUserSettingsOptions = new GetUserSettingsOptions.Builder()
      .accountId(accountId)
      .iamId(userId)
      .build();
    
    Response<UserSettings> response = service.getUserSettings(getUserSettingsOptions).execute();
    UserSettings userSettings = response.getResult();
    
    System.out.println(userSettings);
  • const params = {
      accountId: accountId,
      iamId: userId,
    };
    
    userManagementService.getUserSettings(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • 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

The user settings returned.

The user settings returned.

The user settings returned.

The user settings returned.

The user settings returned.

Status Code

  • The user settings were retrieved successfully.

  • Your access token is not valid, or the authenication of your token failed.

  • Your access token is valid, but it does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • 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
  • {
      "language": "",
      "notification_language": "",
      "allowed_ip_addresses": "111.111.111.111",
      "self_manage": true
    }
  • {
      "language": "",
      "notification_language": "",
      "allowed_ip_addresses": "111.111.111.111",
      "self_manage": true
    }

Partially update user settings

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.

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.

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.

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.

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

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 > name > Access policies.

  • 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

  • The account ID of the specified user.

  • The user's IAM ID.

The user settings returned.

WithContext method only

The UpdateUserSettings options.

The updateUserSettings options.

parameters

  • The account ID.

  • The user's IAM ID.

  • The console UI language. By default, this field is empty.

  • The language for email and phone notifications. By default, this field is empty.

  • A comma-separated list of IP addresses.

    Example: 32.96.110.50,172.16.254.1

  • Whether user managed login is enabled. The default value is false.

parameters

  • The account ID.

  • The user's IAM ID.

  • The console UI language. By default, this field is empty.

  • The language for email and phone notifications. By default, this field is empty.

  • A comma-separated list of IP addresses.

    Example: 32.96.110.50,172.16.254.1

  • Whether user managed login is enabled. The default value is false.

  • 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"
        }'
  • 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)
    }
  • UpdateUserSettingsOptions updateUserSettingsOptions = new UpdateUserSettingsOptions.Builder()
      .accountId(accountId)
      .iamId(userId)
      .selfManage(true)
      .allowedIpAddresses("192.168.0.2,192.168.0.3")
      .build();
    
    service.updateUserSettings(updateUserSettingsOptions).execute();
  • const params = {
      accountId: accountId,
      iamId: userId,
      selfManage: true,
      allowedIpAddresses: '192.168.0.2,192.168.0.3',
    };
    
    userManagementService.updateUserSettings(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • 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))

Response

Status Code

  • The user settings were updated successfully.

  • Your access token is not valid, or the authenication of your token failed.

  • Your access token is valid, but it does not have the necessary permissions to access this resource.

  • The resource could not be found.

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