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