IBM Cloud Pak for Data Platform API

Create and manage user accounts, user groups, and roles on IBM® Cloud Pak for Data using the Cloud Pak for Data REST API.

Introduction

As an administrator, you are responsible for determining and implementing the best approach for authenticating and managing Cloud Pak for Data users.

You can perform the following tasks using the Cloud Pak for Data REST API:

Manage user and user group permissions.

A Cloud Pak for Data administrator can create and manage roles, which grant permissions to users and groups on the platform.

A user can have multiple roles. The roles can be assigned directly to a user or can be assigned to the user through a user group. If a user has multiple roles, the user has all of the permissions from all of the roles that are assigned to them.

User groups make it easier to manage a large number of users with similar access requirements. For example, if you know that 20 different users are going to collaborate on a project and they all need the Data steward role, you can add them to a group that is assigned the Data steward role. If a member of the group leaves the company, you can remove the user from the group, rather than look for and update all of the assets that the user has access to.

Create and manage user profiles.

Authenticated users can perform tasks such as updating their own user-profile info, generating an API key, or changing their password.

Otherwise, you need either the administrator or manage_users permissions to be able to create, update and delete user-profiles.

Authentication

To authenticate to the API, pass a bearer access token or platform API key token in an Authorization header.

Using Authorization: Bearer token

If Identity and Access Management (IAM) are not enabled, you can generate a token by using your username and password against the Get authorization token endpoint.

If IAM is enabled, you can generate a token by using your username and password against the /idprovider/v1/auth/identitytoken endpoint.

Using Authorization: ZenApiKey token

With a platform API key, you can access everything that you would typically be able to access when you log in to the Cloud Pak for Data web client.

Note: Watson™ Data APIs and Watson Machine Learning APIs do not support ZenApiKey authorization.

To generate a platform API key through the user experience:

Log in to the web client.
From the toolbar, click your avatar.
Click Profile and settings.
Click API key > Generate new key.
Click Generate.
Click Copy and save your key somewhere safe. You cannot recover this key if you lose it.

Alternatively, you may call the Generate API key method. Note: this method must be called with bearer access token authorization.

Once you get the API Key from the user experience or from the "generate API Key" method, you should base64 encode <username>:<api_key> to get the token.

Generating an access token using the Get authorization token endpoint. The response includes a token property.

Replace {cpd_cluster_host} with the details for the service instance. Replace {username} and {password} with your IBM Cloud Pak for Data credentials.

curl -k -X POST -d "{\"username\":\"{username}\",\"password\":\"{password}\"}" "https://{cpd_cluster_host}/icp4d-api/v1/authorize"

Alternatively, you can use an API key instead of a password. Replace {username} and {api_key} with your IBM Cloud Pak for Data credentials.

curl -k -X POST -d "{\"username\":\"{username}\",\"api_key\":\"{api_key}\"}" "https://{cpd_cluster_host}/icp4d-api/v1/authorize"

Authenticating to the API using an access token. Replace {token} with your details.

curl -H "Authorization: Bearer {token}" "https://{cpd_cluster_host}/v1/{method}"

Authenticating to the API using a base64 encoded API key token. Replace {token} with your details.

Generate the token using an API key and its respective username.

echo "<username>:<api_key>" | base64

curl -H "Authorization: ZenApiKey {token}" "https://{cpd_cluster_host}/v1/{method}"

Service endpoint

The service endpoint is based on your IBM Cloud Pak deployment URL.

https://{cpd_cluster_host}/usermgmt/v1/{method}

For example, if your instance is deployed at https://www.example.com:31843, you can access the APIs at https://www.example.com:31843/usermgmt/v1/{method}.

Example

curl -H "Authorization: Bearer {token}" -X {request_method} "https://{cpd_cluster_host}/usermgmt/v1/{method}"

Disabling SSL verification

All Cloud Pak for Data services use Secure Sockets Layer (SSL) (or Transport Layer Security (TLS)) for secure connections between the client and server. The connection is verified against the local certificate store to ensure authentication, integrity, and confidentiality.

If you use a self-signed certificate, you need to disable SSL verification to make a successful connection.

Enabling SSL verification is highly recommended. Disabling SSL jeopardizes the security of the connection and data. Disable SSL only if absolutely necessary, and take steps to enable SSL as soon as possible.

To disable SSL verification for a curl request, use the --insecure (-k) option with the request.

Example that disables SSL verification

curl -k -X {request_method} -H "Authorization: Bearer {token}" "{url}/v1/{method}"

Error handling

IBM Cloud Pak for Data uses standard HTTP response codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user. Response codes are listed with the method.

ErrorResponse

Name	Description
_messageCode_{: .parameter-name} string	An identifier of the response.
statusCode{: .parameter-name} integer	The HTTP response code.
exception{: .parameter-name} string	An explanation of the problem.
message{: .parameter-name} string	An explanation of the `_messageCode_`.

IBM Cloud Pak for Data docs
IBM Cloud Pak for Data available APIs

This API allows users to view configuration information for the usermgmt environment and LDAP.

GET /usermgmt/v1/usermgmt/config

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>
Accept-Language
string
Pass language for translated content.

Example: en-US

Query Parameters

includeAll
boolean
Set to true to return all configurations.

Default: false
Example: true

Example request

curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/config?includeAll={includeAll}' -H 'Accept-Language: en-US' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'

Response

Response Body

Config

Status Code

200
Success
400
Bad Request
401
Unauthorized

Example responses

Status 200

{
  "ibm_product": "zen",
  "ibm_product_name": "IBM Cloud Pak for Data",
  "show_user_approval": false,
  "dark_login_theme": false,
  "is_saas": false,
  "externalAuth": true,
  "default_main_url": "/",
  "configure_iam_link": "<url>",
  "ibm_default_product_name": "IBM Cloud Pak for Data",
  "permissions": [
    {
      "key": "manage_vaults_and_secrets",
      "label": "Manage vaults and secrets",
      "displayName": "Manage vaults and secrets",
      "category": "Vaults",
      "category_description": [
        "Secrets are sensitive data such as credentials or API keys. A vault is a secure place to store and manage secrets.",
        "Users can add secrets to the internal vault or connect to an external vault to use existing secrets. By default only the user who added the secret can use the secret."
      ],
      "description": [
        "Users with this permission can see a list of all of the external vaults that users connected to and the list of secrets in each vault. However users with this permission cannot see detailed information about the vaults or access the secrets in the vaults.",
        "Users with this permission can remove secrets from any vault and remove connections to any external vault."
      ],
      "actions": [
        {
          "description": "View list of all connected vaults",
          "tooltip": null
        },
        {
          "description": "View list of all secrets in each vault",
          "tooltip": "Users with this permission cannot see detailed information about the secrets."
        },
        {
          "description": "Remove external vaults",
          "tooltip": null
        },
        {
          "description": "Remove secrets added from an external vault",
          "tooltip": null
        },
        {
          "description": "Delete secrets from the internal vault",
          "tooltip": null
        }
      ]
    }
  ]
}

Status 200

{
  "auto_signup": false,
  "comment": "This is the default out of the box settings - no ldap or policy setup. auto signup disabled.",
  "externalLDAPHost": "",
  "externalLDAPMechanism": "search",
  "externalLDAPPort": 389,
  "externalLDAPSuffix": "ou=Peopledn=ibmdn=com",
  "ibm_product": "zen",
  "ibm_product_name": "IBM Cloud Pak for Data",
  "show_user_approval": false,
  "dark_login_theme": false,
  "is_saas": false,
  "externalAuth": true,
  "default_main_url": "/",
  "configure_iam_link": "<url>",
  "ibm_default_product_name": "IBM Cloud Pak for Data",
  "permissions": [
    {
      "key": "manage_vaults_and_secrets",
      "label": "Manage vaults and secrets",
      "displayName": "Manage vaults and secrets",
      "category": "Vaults",
      "category_description": [
        "Secrets are sensitive data such as credentials or API keys. A vault is a secure place to store and manage secrets.",
        "Users can add secrets to the internal vault or connect to an external vault to use existing secrets. By default only the user who added the secret can use the secret."
      ],
      "description": [
        "Users with this permission can see a list of all of the external vaults that users connected to and the list of secrets in each vault. However users with this permission cannot see detailed information about the vaults or access the secrets in the vaults.",
        "Users with this permission can remove secrets from any vault and remove connections to any external vault."
      ],
      "actions": [
        {
          "description": "View list of all connected vaults",
          "tooltip": null
        },
        {
          "description": "View list of all secrets in each vault",
          "tooltip": "Users with this permission cannot see detailed information about the secrets."
        },
        {
          "description": "Remove external vaults",
          "tooltip": null
        },
        {
          "description": "Remove secrets added from an external vault",
          "tooltip": null
        },
        {
          "description": "Delete secrets from the internal vault",
          "tooltip": null
        }
      ]
    }
  ]
}

Status 400

{
  "_messageCode_": "bad_request",
  "message": "Payload is invalid",
  "_statusCode_": 400,
  "exception": "Request validation failed: Parameter (includeAll) is not a valid boolean: notABool"
}

This API allows users with an administrator role to update configuration values.

PUT /usermgmt/v1/usermgmt/config

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Request Body

object

Examples:

default

Example request

curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/config' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{
  auto_signup: {auto_signup},
  externalLDAPEmailField: {externalLDAPEmailField},
  externalLDAPFirstNameField: {externalLDAPFirstNameField},
  externalLDAPGroupField: {externalLDAPGroupField},
  externalLDAPGroupMemberField: {externalLDAPGroupMemberField},
  externalLDAPGroupSearchBase: {externalLDAPGroupSearchBase},
  externalLDAPGroupSearchField: {externalLDAPGroupSearchField},
  externalLDAPHost: {externalLDAPHost},
  externalLDAPLastNameField: {externalLDAPLastNameField},
  externalLDAPPort: {externalLDAPPort},
  externalLDAPSearchBase: {externalLDAPSearchBase},
  externalLDAPSearchField: {externalLDAPSearchField},
  externalLDAPSearchPassword: {externalLDAPSearchPassword},
  externalLDAPSearchUser: {externalLDAPSearchUser},
  externalLDAPPrefix: {externalLDAPPrefix},
  externalLDAPSuffix: {externalLDAPSuffix}
}'

Response

Response Body

baseError

Status Code

200
Success
400
Bad Request
401
Unauthorized

Example responses

Status 200

{
  "_messageCode_": "success",
  "message": "success"
}

Status 400

{
  "_messageCode_": "bad_request",
  "message": "Payload is invalid",
  "_statusCode_": 400,
  "exception": "Request validation failed: Parameter (body) failed schema validation"
}

This API allows users to test their LDAP configuration.

POST /usermgmt/v1/preauth/validateConfig

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Form Parameters

auto_signup
Required*
boolean
Automatically approve users who request access, without explicit admin approval.
externalLDAPEmailField
Required*
string
Email field in a user entry.

Example: mail
externalLDAPFirstNameField
Required*
string
First name field in a user entry.

Example: givenName
externalLDAPGroupField
Required*
string
Group field in a user entry.

Example: memberOf
externalLDAPGroupMemberField
Required*
string
Member field in a LDAP group entry.

Example: member
externalLDAPGroupSearchBase
Required*
string
Point in the LDAP tree where groups are searched from.

Example: dc=wdp,dc=com
externalLDAPGroupSearchField
Required*
string
LDAP field used for Group search criteria.

Example: cn
externalLDAPHost
Required*
string
The LDAP server's host.

Example: ldap://<host>
externalLDAPLastNameField
Required*
string
Last name field in a user entry.

Example: sn
externalLDAPPort
Required*
number
The LDAP server's port.

Example: 389
externalLDAPPrefix
Required*
string
The LDAP server's prefix.
externalLDAPSearchBase
Required*
string
The LDAP server's search base.

Example: dc=wdp,dc=com
externalLDAPSearchField
Required*
string
The LDAP server's search field.

Example: mail
externalLDAPSearchUser
Required*
string
The LDAP server's search user.

Example: search.user@wdp.com
password
Required*
string
The password for login in clear text.

Example: password
username
Required*
string
The user name for login.

Example: username

Example request

curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/preauth/validateConfig' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer {token}' --data-urlencode 'externalLDAPHost{externalLDAPHost}=' --data-urlencode 'externalLDAPPort{externalLDAPPort}=' --data-urlencode 'username{username}=' --data-urlencode 'password{password}=' --data-urlencode 'externalLDAPMechanism{externalLDAPMechanism}=' --data-urlencode 'externalLDAPPrefix={externalLDAPPrefix}' --data-urlencode 'externalLDAPSuffix={externalLDAPSuffix}' --data-urlencode 'externalLDAPSearchUser={externalLDAPSearchUser}' --data-urlencode 'externalLDAPSearchPassword{externalLDAPSearchPassword}=' --data-urlencode 'externalLDAPSearchBase={externalLDAPSearchBase}' --data-urlencode 'externalLDAPSearchField{externalLDAPSearchField}=' --data-urlencode 'externalLDAPGroupField{externalLDAPGroupField}='

Response

Response Body

baseError

Status Code

200
Success
401
Unauthorized
500
Internal Server Error
503
LDAP Service Unavailable

Example responses

Status 500

{
  "_messageCode_": "ldap_fail",
  "message": "ldap_fail",
  "_statusCode_": 500
}

This API generates a bearer token for a user using their Cloud Pak for Data credentials.

POST /icp4d-api/v1/authorize

Request

Request Body

Required*

loginCredentials

Examples:

username-password

username-api_key

Example request (Username-Password)

curl -k -X POST -H "cache-control: no-cache" -H "Content-Type: application/json" -d "{\"username\":\"{username}\",\"password\":\"{password}\"}" "https://{cpd_cluster_host}/icp4d-api/v1/authorize"

Example request (API Key)

curl -k -X POST -H "cache-control: no-cache" -H "Content-Type: application/json" -d "{\"username\":\"{username}\",\"api_key\":\"{api_key}\"}" "https://{cpd_cluster_host}/icp4d-api/v1/authorize"

Response

Response Body

loginResponse

Status Code

200
Success
400
Bad Request
401
Unauthorized
500
Internal Server Error

Example responses

Status 200

{
  "_messageCode_": "200",
  "message": "Success",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Status 400

{
  "_statusCode_": 400,
  "exception": "Please provide one of api_key/password to receive the token.",
  "message": "Bad Request"
}

Status 401

{
  "_statusCode_": 401,
  "exception": "User unauthorized to invoke this endpoint.",
  "message": "Unauthorized"
}

Status 500

{
  "_statusCode_": 500,
  "message": "Internal server error"
}

This API allows users to view and filter a list of user details on the platform.

Details include user info, groups, roles, and permissions related to the user.

GET /usermgmt/v1/usermgmt/users

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Query Parameters

includeAll
boolean
Set to true to return all users including users in pending/denied access states.

Example: true
search_str
string
Specify search string for pattern matching.

Example: example
permissions
string
Comma separated string - return list of users with one of the permissions.

Example: manage_vaults_and_secrets,share_secrets
user_roles
string
Comma separated string - return list of users with one of the roles.

Example: administrator_role,custom_user_role
roles
string
Comma separated string - return list of users with one of the roles assigned individually or via User-Groups.

Example: api_admin,api_developer
negate_user_roles
boolean
Flag to retrieve users that do not belong to mentioned user_roles.

Example: true
any_role
boolean
Flag to retrieve users having at least one role assigned.

Example: true
no_roles
boolean
Flag to retrieve users having no roles assigned.

Example: true
user_groups
string
Comma separated string - return list of group_ids.

Example: 10000,10001
negate_user_groups
boolean
Flag to retrieve users that do not belong to mentioned user_groups.

Example: true
include_users_count
boolean
Flag to retrieve count of all Cloud Pak for Data users.

Example: true
offset
number
Offset required for pagination.
limit
number
Max number of records to return in a page.

Example: 25
sort_by
string
Sort user records based on a specific column.

Allowable values: [uid,username,displayName,email,created_timestamp]
Example: created_timestamp
sort_order
string
Sorting order either ascending or descending.

Allowable values: [ASC,DESC]
Default: DESC
Example: DESC
include_groups
boolean
Set to true to return groups for each user.

Default: true
Example: true
include_profile_picture
boolean
Set to true to return profile icon for each user.

Default: false
Example: true

Example request

curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/users?includeAll={includeAll}&search_str={search_str}&permissions={permissions}&user_roles={user_roles}&roles={roles}&negate_user_roles={negate_user_roles}&any_role={any_role}&no_roles={no_roles}&user_groups={user_groups}&negate_user_groups={negate_user_groups}&include_users_count={include_users_count}&offset={offset}&limit={limit}&sort_by={sort_by}&sort_order={sort_order}&include_groups={include_groups}&include_profile_picture={include_profile_picture}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'

Response

Response Body

User[]

Status Code

200
Success
400
Bad Request
401
Unauthorized

Example responses

Status 200

[
  {
    "authenticator": "external",
    "created_timestamp": 1655162210393,
    "current_account_status": "enabled",
    "deletable": true,
    "displayName": "example",
    "email": "example@ibm.com",
    "group_roles": [
      "administrator",
      "can_provision"
    ],
    "groups": [
      {
        "group_id": 10000,
        "name": "All users",
        "description": "All users are implicitly part of this group.",
        "added_separately": true,
        "created_at": "2022-05-25T22:03:31.193Z",
        "created_by": "admin",
        "updated_at": "2022-05-25T22:03:31.193Z",
        "members_count": 42,
        "misc": {
          "extAttributes": {
            "nationality": "United States",
            "organization": "IBM",
            "location": "San Jose"
          },
          "realm_name": "openLDAP",
          "dark_mode": true
        }
      }
    ],
    "internal_user": false,
    "last_modified_timestamp": 1655162210393,
    "permissions": [
      "manage_vaults_and_secrets",
      "share_secrets"
    ],
    "profile_picture": "iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=",
    "role": "Admin",
    "uid": 1000331015,
    "user_roles": [
      "administrator_role"
    ],
    "username": "example",
    "misc": {
      "extAttributes": {
        "nationality": "United States",
        "organization": "IBM",
        "location": "San Jose"
      },
      "realm_name": "openLDAP",
      "dark_mode": true
    }
  }
]

Status 400

{
  "exception": "Request validation failed: Parameter (includeAll) is not a valid boolean: notABool",
  "_messageCode_": "bad_request",
  "message": "Payload is invalid",
  "_statusCode_": 400
}

This API allows users to view details about one user via their user ID.

GET /usermgmt/v1/usermgmt/user/{uid}

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Path Parameters

uid
Required*
string
Query for user profile by given user ID.

Example: 1000331015

Example request

curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/user/{uid}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'

Response

Response Body

User

Status Code

200
Success
400
Bad Request
404
Not Found

Example responses

Status 200

{
  "authenticator": "external",
  "created_timestamp": 1655162210393,
  "current_account_status": "enabled",
  "deletable": true,
  "displayName": "example",
  "email": "example@ibm.com",
  "group_roles": [
    "administrator",
    "can_provision"
  ],
  "groups": [
    {
      "group_id": 10000,
      "name": "All users",
      "description": "All users are implicitly part of this group.",
      "added_separately": true,
      "created_at": "2022-05-25T22:03:31.193Z",
      "created_by": "admin",
      "updated_at": "2022-05-25T22:03:31.193Z",
      "members_count": 42,
      "misc": {
        "extAttributes": {
          "nationality": "United States",
          "organization": "IBM",
          "location": "San Jose"
        },
        "realm_name": "openLDAP",
        "dark_mode": true
      }
    }
  ],
  "internal_user": false,
  "last_modified_timestamp": 1655162210393,
  "permissions": [
    "manage_vaults_and_secrets",
    "share_secrets"
  ],
  "profile_picture": "iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=",
  "role": "Admin",
  "uid": 1000331015,
  "user_roles": [
    "administrator_role"
  ],
  "username": "example",
  "misc": {
    "extAttributes": {
      "nationality": "United States",
      "organization": "IBM",
      "location": "San Jose"
    },
    "realm_name": "openLDAP",
    "dark_mode": true
  }
}

Status 400

{
  "exception": "UID is invalid",
  "_messageCode_": "bad_request",
  "message": "Payload is invalid",
  "_statusCode_": 400
}

Status 404

{
  "exception": "user details not found",
  "_messageCode_": "not_found",
  "message": "The asset is not found",
  "_statusCode_": 404
}

This API allows users with an administrator role to grant Cloud Pak for Data platform access to a user.

The password field should not be included when creating a user authenticated via an external identity provider such as LDAP/SAML/IAM. It is highly encouraged to authenticate users via an external identity provider.

POST /usermgmt/v1/user

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Query Parameters

migrated
boolean
Set to true when this endpoint is used for migration purposes.

Request Body

User

Examples:

User

User with External Attributes

Admin User

LDAP User

Create User Sample Request

curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{
  "displayName":{displayName},
  "email":{email},
  "username":{username},
  "password":{password},
  "user_roles":{user_roles}
}'

Create LDAP User Sample Request

curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{
  "username":{username},
  "displayName":{displayName},
  "email":{email},
  "authenticator":{authenticator},
  "user_roles":{user_roles},
  "misc": {
    "realm_name":{realm_name},
    "extAttributes":{extAttributes}
  }
}'

Response

Response Body

object

Status Code

200
Success
400
Bad Request
401
Unauthorized
404
Not Found

Example responses

Status 200

{
  "uid": "1000331013",
  "_messageCode_": "success",
  "message": "success"
}

Status 400

{
  "exception": "requested_role_does_not_exist",
  "_messageCode_": "createUser_fail",
  "message": "Adding user record failed",
  "_statusCode_": 400
}

This API allows users to view a list of user details filtered by user IDs.

GET /usermgmt/v1/users

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Query Parameters

uids
string
Comma-separated string of user IDs.

Example: 1,2
count_only
boolean
Flag to send numbers of users in response.

Example: true

Example request

curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/users?uids={uids}&count_only={count_only}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'

Response

Response Body

User[]

Status Code

200
Success
400
Bad Request
401
Unauthorized

Example responses

Status 200

{
  "user_count": 42,
  "success": true,
  "_messageCode_": "Success",
  "message": "Success"
}

Status 200

{
  "users": [
    {
      "uid": "1000331015",
      "username": "example",
      "displayName": "example",
      "email": "example@ibm.com",
      "permissions": [
        "manage_vaults_and_secrets",
        "share_secrets"
      ],
      "user_roles": [
        "administrator_role"
      ],
      "current_account_status": "enabled",
      "internal_user": false,
      "deletable": true,
      "authenticator": "external",
      "created_timestamp": 1655162210302,
      "last_modified_timestamp": 1655162210302,
      "misc": {
        "extAttributes": {},
        "realm_name": "testConn1",
        "dark_mode": false
      },
      "profile_picture": "",
      "is_custom_picture": false,
      "role": "Admin",
      "groups": [
        {
          "group_id": 10000,
          "name": "All users",
          "description": "All users are implicitly part of this group.",
          "created_by": null,
          "created_at": null,
          "updated_at": null,
          "misc": {},
          "members_count": 73
        }
      ],
      "group_roles": []
    }
  ],
  "success": true
}

Status 400

{
  "exception": "Request validation failed: Parameter (count_only) is not a valid boolean: notABool",
  "_messageCode_": "bad_request",
  "message": "Payload is invalid",
  "_statusCode_": 400
}

This API allows users with an administrator role to grant Cloud Pak for Data platform access to multiple users.

The password field should not be included when creating a user authenticated via an external identity provider such as LDAP/SAML/IAM. It is highly encouraged to authenticate users via an external identity provider.

POST /usermgmt/v1/user/bulk

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Request Body

Required*

User[]

List of user objects.

Examples:

Multiple Users

Example request

curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/bulk' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '[
  {
    "displayName":{displayName},
    "email":{email},
    "username":{username},
    "password":{password},
    "user_roles":{user_roles}
  }
]'

Response

Response Body

object

Status Code

200
Success
400
Bad Request
401
Unauthorized
500
Internal Server Error

Example responses

Status 200

{
  "result": [
    {
      "uid": "1000331017",
      "username": "User",
      "displayName": "User",
      "success": "true",
      "message": "User created"
    },
    {
      "uid": "1000331018",
      "username": "User2",
      "displayName": "extAttributes User",
      "success": "true",
      "message": "User created"
    },
    {
      "uid": "",
      "username": "Admin",
      "displayName": "Admin",
      "success": "false",
      "message": "username_exist"
    },
    {
      "uid": "1000331019",
      "username": "ldap.user@example.com",
      "displayName": "LDAP User",
      "success": "true",
      "message": "User created"
    }
  ],
  "_messageCode_": "Success",
  "message": "Success"
}

This API allows the current logged in user to view their user details.

GET /usermgmt/v1/user/currentUserInfo

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Example request

curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/user/currentUserInfo' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'

Response

Response Body

User

Status Code

200
Success
401
Unauthorized
404
Not Found

Example responses

Status 200

{
  "authenticator": "external",
  "created_timestamp": 1655162210393,
  "current_account_status": "enabled",
  "deletable": true,
  "displayName": "example",
  "email": "example@ibm.com",
  "group_roles": [
    "administrator",
    "can_provision"
  ],
  "groups": [
    {
      "group_id": 10000,
      "name": "All users",
      "description": "All users are implicitly part of this group.",
      "added_separately": true,
      "created_at": "2022-05-25T22:03:31.193Z",
      "created_by": "admin",
      "updated_at": "2022-05-25T22:03:31.193Z",
      "members_count": 42,
      "misc": {
        "extAttributes": {
          "nationality": "United States",
          "organization": "IBM",
          "location": "San Jose"
        },
        "realm_name": "openLDAP",
        "dark_mode": true
      }
    }
  ],
  "internal_user": false,
  "last_modified_timestamp": 1655162210393,
  "permissions": [
    "manage_vaults_and_secrets",
    "share_secrets"
  ],
  "profile_picture": "iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=",
  "role": "Admin",
  "uid": 1000331015,
  "user_roles": [
    "administrator_role"
  ],
  "username": "example",
  "misc": {
    "extAttributes": {
      "nationality": "United States",
      "organization": "IBM",
      "location": "San Jose"
    },
    "realm_name": "openLDAP",
    "dark_mode": true
  }
}

This API allows the current logged in user to view their token expiry details.

GET /usermgmt/v1/user/tokenExpiry

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Example request

curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/user/tokenExpiry' -H 'Authorization: Bearer {token}'

Response

Response Body

object

Status Code

200
Success
401
Unauthorized

Example responses

Status 200

{
  "exp": 1655526084,
  "token_expiry_time": "12"
}

This API allows users to view details about a user via their username.

GET /usermgmt/v1/user/{username}

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Path Parameters

username
Required*
string
The user name.

Example: example

Example request

curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/user/{username}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'

Response

Response Body

User

Status Code

200
Success
400
Bad Request
401
Unauthorized
404
Not Found

Example responses

Status 200

{
  "authenticator": "external",
  "created_timestamp": 1655162210393,
  "current_account_status": "enabled",
  "deletable": true,
  "displayName": "example",
  "email": "example@ibm.com",
  "group_roles": [
    "administrator",
    "can_provision"
  ],
  "groups": [
    {
      "group_id": 10000,
      "name": "All users",
      "description": "All users are implicitly part of this group.",
      "added_separately": true,
      "created_at": "2022-05-25T22:03:31.193Z",
      "created_by": "admin",
      "updated_at": "2022-05-25T22:03:31.193Z",
      "members_count": 42,
      "misc": {
        "extAttributes": {
          "nationality": "United States",
          "organization": "IBM",
          "location": "San Jose"
        },
        "realm_name": "openLDAP",
        "dark_mode": true
      }
    }
  ],
  "internal_user": false,
  "last_modified_timestamp": 1655162210393,
  "permissions": [
    "manage_vaults_and_secrets",
    "share_secrets"
  ],
  "profile_picture": "iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=",
  "role": "Admin",
  "uid": 1000331015,
  "user_roles": [
    "administrator_role"
  ],
  "username": "example",
  "misc": {
    "extAttributes": {
      "nationality": "United States",
      "organization": "IBM",
      "location": "San Jose"
    },
    "realm_name": "openLDAP",
    "dark_mode": true
  }
}

Status 404

{
  "exception": "user details not found",
  "_messageCode_": "not_found",
  "message": "The asset is not found",
  "_statusCode_": 404
}

This API allows users with an administrator role to update a user's account details via the user's username.

PUT /usermgmt/v1/user/{username}

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Path Parameters

username
Required*
string
Name of the user to update.

Example: example

Query Parameters

add_roles
boolean
If true, roles are added to current roles. Otherwise, roles are overwritten.

Default: false
Example: true

Request Body

updateUserParamsBody

Updated user object.

Examples:

default

Example request

curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v1/user/{username}?add_roles={add_roles}' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{
  "displayName":{displayName},
  "email":{email},
  "username":{username},
  "user_roles":{user_roles}
}'

Response

Response Body

object

Status Code

200
Success
401
Unauthorized
404
Not Found

Example responses

Status 200

{
  "uid": "1000331015",
  "_messageCode_": "success",
  "message": "success"
}

Status 404

{
  "exception": "user details not found",
  "_messageCode_": "not_found",
  "message": "The asset is not found",
  "_statusCode_": 404
}

This API allows users with an administrator role to delete a user via their username.

Note the initial 'admin' user cannot be deleted.

Important: When you delete users, they lose access to the assets that they own, such as projects or deployment spaces. Adding a user with the same ID does not give that user access to the assets that are associated with that ID.

DELETE /usermgmt/v1/user/{username}

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Path Parameters

username
Required*
string
Name of the user to delete.

Example: example

Example request

curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v1/user/{username}' -H 'Authorization: Bearer {token}'

Response

Response Body

object

Status Code

200
Success
401
Unauthorized
404
Not Found

Example responses

Status 200

{
  "uid": "1000331015",
  "_messageCode_": "success",
  "message": "success"
}

Status 404

{
  "exception": "user details not found",
  "_messageCode_": "not_found",
  "message": "The asset is not found",
  "_statusCode_": 404
}

This API allows the current logged in user to renew their Bearer token and session cookie.

POST /usermgmt/v1/user/renewToken

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Query Parameters

expiry_time
string
Token expiry time.

Example: 12

Example request

curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/renewToken?expiry_time={expiry_time}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'

Response

Response Body

object

Successful renew token response body.

Status Code

200
Success
400
Bad Request
401
Unauthorized

Example responses

Status 200

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "csrf_token": "<csrf_token>",
  "_messageCode_": "success",
  "message": "success"
}

This API allows the current logged in user to generate a new API key.

Note that generating a new API key will revoke the older key.

GET /usermgmt/v1/user/apiKey

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Example request

curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/user/apiKey' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'

Response

Response Body

object

Successful API key response body

Status Code

200
Success
400
Bad Request
401
Unauthorized
404
Could not find the user associated with the Bearer token
500
Internal Server Error

Example responses

Status 200

{
  "apiKey": "<api_key>",
  "_messageCode_": "success",
  "message": "success"
}

Status 401

{
  "_messageCode_": "authorization_fail",
  "message": "Not authorized. This action might require additional privileges or administrator permission.",
  "_statusCode_": 401
}

This API allows the current logged in user to delete their current API key.

DELETE /usermgmt/v1/user/apiKey

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Example request

curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v1/user/apiKey' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'

Response

Response Body

object

Successful revoke API key response

Status Code

200
Success
400
Bad Request
401
Unauthorized
404
Could not find the user associated with the Bearer token
500
Internal Server Error

Example responses

Status 200

{
  "_messageCode_": "success",
  "message": "success"
}

This API allows the current logged in user to log out.

GET /usermgmt/v1/usermgmt/logout

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/logout' -H 'Authorization: Bearer {token}'

Response

Status Code

302
Found. Redirecting to <url>
401
Unauthorized

No Sample Response

This method does not specify any sample responses.

This API allows the current logged in user to change their password.

This cannot be done if the user was authenticated via LDAP/SAML/IAM.

POST /usermgmt/v1/user/changemypassword

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Form Parameters

password
Required*
string
The new password.

Example: newPassword
currentPassword
Required*
string
The current password.

Example: currentPassword

Example request

curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/changemypassword' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer {token}' --data-urlencode 'password={password},' --data-urlencode 'currentPassword={currentPassword}'
curl -k -X POST 

Response

Status Code

401
Unauthorized
404
Not Found
default
Success

No Sample Response

This method does not specify any sample responses.

This API allows users with an administrator role to change a user's password.

This cannot be done for a user authenticated via LDAP/SAML/IAM.

POST /usermgmt/v1/user/changeuserpassword

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Form Parameters

username
Required*
string
The user name.

Example: username
password
Required*
string
The new password.

Example: newPassword

Example request

curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/changeuserpassword' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer {token}' --data-urlencode 'username={username}' --data-urlencode 'password={password}'

Response

Status Code

401
Unauthorized
404
Not Found
default
Success

Example responses

Status 404

{
  "exception": "User details not found",
  "_messageCode_": "not_found",
  "message": "The asset is not found",
  "_statusCode_": 404
}

This API allows the current logged in user to update their user profile.

PUT /usermgmt/v2/own_profile

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Query Parameters

dark_mode
boolean
Flag to set theme for user profile.

Example: true

Example request

curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v2/own_profile?dark_mode={dark_mode}' -H 'Authorization: Bearer {token}'

Response

Response Body

object

Successful setOwnProfile response body

Status Code

200
Success
400
Bad Request
401
Unauthorized

Example responses

Status 200

{
  "uid": "1000331015",
  "_messageCode_": "success",
  "message": "success"
}

Status 400

{
  "exception": "Request validation failed: Parameter (dark_mode) is not a valid boolean: notABool",
  "_messageCode_": "bad_request",
  "message": "Payload is invalid",
  "_statusCode_": 400
}

This API allows users to view and filter a list of user group details.

GET /usermgmt/v2/groups

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Query Parameters

group_identifiers
string
Comma separated string of group identifiers.

Example: 10000,10001
role_identifiers
string
Comma separated string of role identifiers.

Example: administrator,api_user
include_members
boolean
Set to true to include details about users in this group.

Default: false

Example request

curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/groups?group_identifiers={group_identifiers}&role_identifiers={role_identifiers}&include_members={include_members}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'

Response

Response Body

GetUserGroup[]

List of user groups.

Status Code

200
Success
400
Bad Request
401
Unauthorized
404
Not Found
500
Internal Server Error

Example responses

Status 200

[
  {
    "group_id": 10000,
    "name": "All users",
    "description": "All users are implicitly part of this group.",
    "created_at": "2022-05-25T22:03:31.193Z",
    "created_by": "admin",
    "updated_at": "2022-05-25T22:03:31.193Z",
    "misc": {
      "isDynamicGroup": false
    },
    "roles": [
      {
        "role_id": "f8898d2f-5d94-4e38-8797-977924982c05",
        "role_name": "api_user"
      }
    ],
    "members_count": "42",
    "permissions": [
      "administrator",
      "can_provision"
    ]
  }
]

Status 400

{
  "_messageCode_": "bad_request",
  "message": "Payload is invalid",
  "_statusCode_": 400,
  "exception": "Request validation failed: Parameter (include_members) is not a valid boolean: notABool"
}

This API allows users with an administrator role to create a user group.

POST /usermgmt/v2/groups

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Request Body

createUserGroupBody

Examples:

default

Example request

curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/groups' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{
  "name": {name},
  "description": {description},
  "account_id": {account_id},
  "role_identifiers": {role_identifiers}
}'

Response

Response Body

object

Status Code

201
Created
400
Bad Request
401
Unauthorized
404
Not Found
409
Conflict
500
Internal Server Error

Example responses

Status 201

{
  "created_at": "2022-06-20T18:21:21.763Z",
  "created_by": "admin",
  "description": "This is a user group description.",
  "group_id": 10001,
  "message": "Created",
  "name": "example group",
  "updated_at": "2022-06-20T18:21:21.763Z",
  "_messageCode_": "Created"
}

Status 400

{
  "_messageCode_": "bad_request",
  "message": "Payload is invalid",
  "_statusCode_": 400,
  "exception": "User-Group must have a name"
}

Status 401

{
  "_messageCode_": "authorization_fail",
  "message": "Not authorized. This action may require additional privileges or the administrator permission",
  "_statusCode_": 401
}

Status 409

{
  "_messageCode_": "conflict_error",
  "message": "Request conflicts with the current state of the server",
  "_statusCode_": 409,
  "exception": "Another usergroup with the same name exists."
}

Status 500

{
  "_messageCode_": "internal_error",
  "message": "Internal server error",
  "_statusCode_": 500,
  "exception": "duplicate key value violates unique constraint \"user_group_roles_group_id_role_id_key\""
}

This API allows users with an administrator role to update user group information.

PATCH /usermgmt/v2/groups/{group_id}

Request

Custom Headers

Authorization
string
Authorization: Bearer <token>

Examples:
Authorization: Bearer <token>
Authorization: ZenApiKey <token>

Path Parameters

group_id
Required*
number
Unique ID indentifying the User-Group.

Example: 10001

Request Body

patchUserGroupBody

Examples:

default

Introduction

Authentication

Using Authorization: Bearer token

Using Authorization: ZenApiKey token

Service endpoint

Disabling SSL verification

Error handling

Related information

Methods

Get configuration info

Request

Custom Headers

Authorization

Accept-Language

Query Parameters

includeAll

Response

Response Body

auto_signup

comment

externalLDAPHost

externalLDAPMechanism

externalLDAPPort

externalLDAPSuffix

ibm_product

ibm_product_name

show_user_approval

dark_login_theme

is_saas

externalAuth

default_main_url

configure_iam_link

ibm_default_product_name

permissions

Status Code

200

400

401

Update configuration

Request

Custom Headers

Authorization

Request Body

auto_signup

externalLDAPEmailField

externalLDAPFirstNameField

externalLDAPGroupField

externalLDAPGroupMemberField

externalLDAPGroupSearchBase

externalLDAPGroupSearchField

externalLDAPHost

externalLDAPLastNameField

externalLDAPPort

externalLDAPSearchBase

externalLDAPSearchField

externalLDAPSearchPassword

externalLDAPSearchUser

externalLDAPPrefix

externalLDAPSuffix

Response

Response Body

_messageCode_

message

Status Code

200

400

401

Test LDAP configuration

Request

Custom Headers

Authorization

Form Parameters

auto_signup

externalLDAPEmailField

externalLDAPFirstNameField

externalLDAPGroupField

externalLDAPGroupMemberField

externalLDAPGroupSearchBase

externalLDAPGroupSearchField

externalLDAPHost