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.

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.

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.

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.

A user can be in the following 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.

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.

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.

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

Get 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 any 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 through the next_url field.

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

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The account ID.

Query Parameters

  • The state of the user.

  • The realm of the user.

Response

Status Code

  • Users were returned successfully.

  • Your access token is not valid, or 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

Invite users

Invite users to 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 the 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 will be generated.

POST /v2/accounts/{account_id}/users
Request

Custom Headers

  • Your IBM Cloud IAM user access token.

Path Parameters

  • The account ID.

Response

Status Code

  • Invite users successfully

  • Your access token is not valid, or 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

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 one of the viewer, editor, or administrator role on the User Management service.

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

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The account ID.

  • The user's IAM ID.

Response

Status Code

  • The user was returned successfully.

  • Your access token is not valid, or 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

Partially update user profiles

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 cannot 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}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The account ID.

  • The user's IAM ID.

Response

Status Code

  • The user profile was updated successfully.

  • The request has an invalid payload.

  • Your access token is not valid, or 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 users

Remove users from an account 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 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}
Request

Custom Headers

  • Your IBM Cloud IAM user access token.

Path Parameters

  • The account ID.

  • The user's IAM ID.

Response

Status Code

  • The user was removed successfully.

  • The request has an invalid payload.

  • Your access token is not valid, or 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, see the explanation about user-managed login in Managing a user's login settings.

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

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The account ID.

  • The user's IAM ID.

Response

Status Code

  • The user settings were retrieved successfully.

  • Your access token is not valid, or 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

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.

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

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The account ID.

  • The user's IAM ID.

Response

Status Code

  • The user settings were updated successfully.

  • Your access token is not valid, or 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