List users

GET /v2/accounts/{account_id}/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. Additional substring search fields are supported to filter the users.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • user-management.cloud-user.list

Auditing

Calling this method generates the following auditing event.

  • user-management.cloud-user.list

Request

Path Parameters

Query Parameters

limit

integer

The number of results to be returned.

include_settings

boolean

The user settings to be returned. Set to true to view language, allowed IP address, and authentication settings.

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

Response

200 - Users were returned successfully.

total_results

integer

The number of users returned.

limit

integer

A limit to the number of users returned in a page.

first_url

string

The first URL of the get users API.

next_url

string

The next URL of the get users API.

resources

array

A list of users in the account.

401 -

403 -

404 -

500 -

Invite users to an account

POST /v2/accounts/{account_id}/users

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • user-management.user.create

Auditing

Calling this method generates the following auditing event.

  • user-management.user.create

Request

Request Body

ReqBodyInviteUser

users

Required *

array

A list of users to be invited.

iam_policy

array

A list of IAM policies.

access_groups

array

A list of access groups.

Response

202 - The user was successfully invited.

resources

array

The list of users that have been invited to join the account.

401 -

403 -

404 -

409 -

500 -

Remove user from account by user ID or email

DELETE /v2/accounts/{account_id}/users

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • user-management.user.delete

Auditing

Calling this method generates the following auditing event.

  • user-management.user.delete

Request

Path Parameters

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

Response

204 - The user was removed successfully.

400 -

401 -

403 -

500 -

Get user profile

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

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • user-management.user.read

Auditing

Calling this method generates the following auditing event.

  • user-management.user.read

Request

Response

200 - The user was returned successfully.

id

string

An alphanumeric value identifying the user profile.

iam_id

string

An alphanumeric value identifying the user's IAM ID.

realm

string

The realm of the user. The value is either `IBMid` or `SL`.

user_id

string

The user ID used for login.

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.

account_id

string

An alphanumeric value identifying the account ID.

added_on

string

The timestamp for when the user was added to the account.

401 -

403 -

404 -

500 -

Partially update user profile

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

The payload allows updates to a user's basic profile information. However, when a user's basic profile is updated, the system always relies on the user's IBMid profile information (such as name, email address, and phone numbers). Although the payload includes fields like name and email for users who are managed by IBMid, the values are always sourced from the IBMid profile. If the user provides any values that are different from the IBMid profile information, the IBMid profile data takes precedence, and the incoming customer-provided data is ignored.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • user-management.user.update

Auditing

Calling this method generates the following auditing event.

  • user-management.user.update

Request

Request Body

ReqBodyUserProfilePatch

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.

Response

204 - The user profile was updated successfully.

400 -

401 -

403 -

500 -

Remove user from account

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

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • user-management.user.delete

Auditing

Calling this method generates the following auditing event.

  • user-management.user.delete

Request

Response

204 - The user was removed successfully.

400 -

401 -

403 -

500 -

Accept an invitation

POST /v2/users/accept

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.

Request

Request Body

ReqBodyAcceptUser

account_id

string

The account ID.

Response

202 - The request was accepted.

400 -

401 -

403 -

500 -

Remove user from account (Asynchronous)

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

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • user-management.user.delete

Auditing

Calling this method generates the following auditing event.

  • user-management.user.delete

Request

Response

202 - The request was accepted.

400 -

401 -

403 -

500 -

Bulk remove users from account

POST /v2/accounts/{account_id}/users_bulk_delete

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • user-management.user.delete

Auditing

Calling this method generates the following auditing event.

  • user-management.user.bulk-delete

Request

Request Body

ReqBodyBulkUserRemove

users

array

The list of user IAM IDs

Response

207 - There is a multiple status response. Check the response body.

account_id

string

An alphanumeric value identifying the account ID.

users

array

The iam_ids removed from the account.

400 -

401 -

403 -

500 -

Get user settings

GET /v2/accounts/{account_id}/users/{iam_id}/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. <br/><br/>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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • user-management.user-setting.read

Auditing

Calling this method generates the following auditing event.

  • user-management.user-setting.read

Request

Response

200 - The user settings were retrieved successfully.

language

string

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

notification_language

string

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

allowed_ip_addresses

string

A comma-separated list of IP addresses.

self_manage

boolean

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

401 -

403 -

404 -

500 -

Partially update user settings

PATCH /v2/accounts/{account_id}/users/{iam_id}/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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • user-management.user-setting.update

Auditing

Calling this method generates the following auditing event.

  • user-management.user-setting.update

Request

Request Body

UserSettings

language

string

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

notification_language

string

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

allowed_ip_addresses

string

A comma-separated list of IP addresses.

self_manage

boolean

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

Response

204 - The user settings were updated successfully.

401 -

403 -

404 -

500 -