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. SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

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

User account status

A user can be in the following states.

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

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

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

Maven

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

Gradle

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

View on GitHub

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

Installing the Go SDK

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

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

Go get

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

View on GitHub

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

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

Installation

npm install @ibm-cloud/platform-services

View on GitHub

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

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

Installation

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

View on GitHub

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

Endpoint URLs

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

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

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

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

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

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

Example API request

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

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

Authentication

Authorization to the user management REST API is enforced by using an IAM access token. The token is used to determine the roles that the identity has access to when using user management services. For information about how to obtain an IAM token for an authenticated user or service ID, see the IAM Identity Service API documentation.

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

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

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

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

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

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

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

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

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

To retrieve your access token:

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

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

Example that sets options by using environment variables

export USER_MANAGEMENT_APIKEY=<API_KEY>

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

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

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

Example that sets options by using environment variables

export USER_MANAGEMENT_APIKEY=<API_KEY>

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

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

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

Example that sets options by using environment variables

export USER_MANAGEMENT_APIKEY=<API_KEY>

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

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

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

Example that sets options by using environment variables

export USER_MANAGEMENT_APIKEY=<API_KEY>

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

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

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

Auditing

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

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

Error handling

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

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

User Management | IBM Cloud API Docs