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:

  1. Log in to the web client.
  2. From the toolbar, click your avatar.
  3. Click Profile and settings.
  4. Click API key > Generate new key.
  5. Click Generate.
  6. 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_.

Methods

Get configuration info

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

GET /v1/usermgmt/config

Request

Custom Headers

  • Authorization: Bearer <token>

    Examples:
    Authorization: Bearer <token>
    Authorization: ZenApiKey <token>
  • Pass language for translated content.

    Example: en-US

Query Parameters

  • Set to true to return all configurations.

    Default: false

    Example: true

  • 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

Status Code

  • Success

  • Bad Request

  • Unauthorized

Example responses
  • {
      "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
            }
          ]
        }
      ]
    }
  • {
      "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
            }
          ]
        }
      ]
    }
  • {
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400,
      "exception": "Request validation failed: Parameter (includeAll) is not a valid boolean: notABool"
    }

Update configuration

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

PUT /v1/usermgmt/config

Request

Custom Headers

  • Authorization: Bearer <token>

    Examples:
    Authorization: Bearer <token>
    Authorization: ZenApiKey <token>
Examples:
default
  • 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

Status Code

  • Success

  • Bad Request

  • Unauthorized

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

Test LDAP configuration

This API allows users to test their LDAP configuration.

POST /v1/preauth/validateConfig

Request

Custom Headers

  • Authorization: Bearer <token>

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

Form Parameters

  • Automatically approve users who request access, without explicit admin approval.

  • Email field in a user entry.

    Example: mail

  • First name field in a user entry.

    Example: givenName

  • Group field in a user entry.

    Example: memberOf

  • Member field in a LDAP group entry.

    Example: member

  • Point in the LDAP tree where groups are searched from.

    Example: dc=wdp,dc=com

  • LDAP field used for Group search criteria.

    Example: cn

  • The LDAP server's host.

    Example: ldap://<host>

  • Last name field in a user entry.

    Example: sn

  • The LDAP server's port.

    Example: 389

  • The LDAP server's prefix.

  • The LDAP server's search base.

    Example: dc=wdp,dc=com

  • The LDAP server's search field.

    Example: mail

  • The LDAP server's search user.

    Example: search.user@wdp.com

  • The password for login in clear text.

    Example: password

  • The user name for login.

    Example: username

  • 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

Status Code

  • Success

  • Unauthorized

  • Internal Server Error

  • LDAP Service Unavailable

Example responses
  • {
      "_messageCode_": "ldap_fail",
      "message": "ldap_fail",
      "_statusCode_": 500
    }

Get authorization token

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

POST /icp4d-api/v1/authorize

Request

Examples:
username-password
username-api_key
  • 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"
  • 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

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Internal Server Error

Example responses
  • {
      "_messageCode_": "200",
      "message": "Success",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }
  • {
      "_statusCode_": 400,
      "exception": "Please provide one of api_key/password to receive the token.",
      "message": "Bad Request"
    }
  • {
      "_statusCode_": 401,
      "exception": "User unauthorized to invoke this endpoint.",
      "message": "Unauthorized"
    }
  • {
      "_statusCode_": 500,
      "message": "Internal server error"
    }

Get users

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 /v1/usermgmt/users

Request

Custom Headers

  • Authorization: Bearer <token>

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

Query Parameters

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

    Example: true

  • Specify search string for pattern matching.

    Example: example

  • Comma separated string - return list of users with one of the permissions.

    Example: manage_vaults_and_secrets,share_secrets

  • Comma separated string - return list of users with one of the roles.

    Example: administrator_role,custom_user_role

  • Comma separated string - return list of users with one of the roles assigned individually or via User-Groups.

    Example: api_admin,api_developer

  • Flag to retrieve users that do not belong to mentioned user_roles.

    Example: true

  • Flag to retrieve users having at least one role assigned.

    Example: true

  • Flag to retrieve users having no roles assigned.

    Example: true

  • Comma separated string - return list of group_ids.

    Example: 10000,10001

  • Flag to retrieve users that do not belong to mentioned user_groups.

    Example: true

  • Flag to retrieve count of all Cloud Pak for Data users.

    Example: true

  • Offset required for pagination.

  • Max number of records to return in a page.

    Example: 25

  • Sort user records based on a specific column.

    Allowable values: [uid,username,displayName,email,created_timestamp]

    Example: created_timestamp

  • Sorting order either ascending or descending.

    Allowable values: [ASC,DESC]

    Default: DESC

    Example: DESC

  • Set to true to return groups for each user.

    Default: true

    Example: true

  • Set to true to return profile icon for each user.

    Default: false

    Example: true

  • 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

Status Code

  • Success

  • Bad Request

  • Unauthorized

Example responses
  • [
      {
        "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
        }
      }
    ]
  • {
      "exception": "Request validation failed: Parameter (includeAll) is not a valid boolean: notABool",
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400
    }

Get user by ID

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

GET /v1/usermgmt/user/{uid}

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • Query for user profile by given user ID.

    Example: 1000331015

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

Response

Status Code

  • Success

  • Bad Request

  • Not Found

Example responses
  • {
      "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
      }
    }
  • {
      "exception": "UID is invalid",
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400
    }
  • {
      "exception": "user details not found",
      "_messageCode_": "not_found",
      "message": "The asset is not found",
      "_statusCode_": 404
    }

Grant access to user

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 /v1/user

Request

Custom Headers

  • Authorization: Bearer <token>

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

Query Parameters

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

Examples:
User
User with External Attributes
Admin User
LDAP User
  • curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user?migrated={migrated}' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{
      "displayName":{displayName},
      "email":{email},
      "username":{username},
      "password":{password},
      "user_roles":{user_roles}
    }'
    
  • curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user?migrated={migrated}' -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

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

Example responses
  • {
      "uid": "1000331013",
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "exception": "requested_role_does_not_exist",
      "_messageCode_": "createUser_fail",
      "message": "Adding user record failed",
      "_statusCode_": 400
    }

Get users by ID

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

GET /v1/users

Request

Custom Headers

  • Authorization: Bearer <token>

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

Query Parameters

  • Comma-separated string of user IDs.

    Example: 1,2

  • Flag to send numbers of users in response.

    Example: true

  • 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

Status Code

  • Success

  • Bad Request

  • Unauthorized

Example responses
  • {
      "user_count": 42,
      "success": true,
      "_messageCode_": "Success",
      "message": "Success"
    }
  • {
      "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
    }
  • {
      "exception": "Request validation failed: Parameter (count_only) is not a valid boolean: notABool",
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400
    }

Grant access to multiple users

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 /v1/user/bulk

Request

Custom Headers

  • Authorization: Bearer <token>

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

List of user objects.

Examples:
Multiple Users
  • 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

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Internal Server Error

Example responses
  • {
      "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"
    }

Get current user info

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

GET /v1/user/currentUserInfo

Request

Custom Headers

  • Authorization: Bearer <token>

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

Response

Status Code

  • Success

  • Unauthorized

  • Not Found

Example responses
  • {
      "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
      }
    }

Get current user's token expiry

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

GET /v1/user/tokenExpiry

Request

Custom Headers

  • Authorization: Bearer <token>

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

Response

Status Code

  • Success

  • Unauthorized

Example responses
  • {
      "exp": 1655526084,
      "token_expiry_time": "12"
    }

Get user by name

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

GET /v1/user/{username}

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • The user name.

    Example: example

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

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

Example responses
  • {
      "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
      }
    }
  • {
      "exception": "user details not found",
      "_messageCode_": "not_found",
      "message": "The asset is not found",
      "_statusCode_": 404
    }

Update user

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

PUT /v1/user/{username}

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • Name of the user to update.

    Example: example

Query Parameters

  • If true, roles are added to current roles. Otherwise, roles are overwritten.

    Default: false

    Example: true

Updated user object.

Examples:
default
  • 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

Status Code

  • Success

  • Unauthorized

  • Not Found

Example responses
  • {
      "uid": "1000331015",
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "exception": "user details not found",
      "_messageCode_": "not_found",
      "message": "The asset is not found",
      "_statusCode_": 404
    }

Delete user

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 /v1/user/{username}

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • Name of the user to delete.

    Example: example

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

Response

Status Code

  • Success

  • Unauthorized

  • Not Found

Example responses
  • {
      "uid": "1000331015",
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "exception": "user details not found",
      "_messageCode_": "not_found",
      "message": "The asset is not found",
      "_statusCode_": 404
    }

Renew token

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

POST /v1/user/renewToken

Request

Custom Headers

  • Authorization: Bearer <token>

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

Query Parameters

  • Token expiry time.

    Example: 12

  • 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

Successful renew token response body.

Status Code

  • Success

  • Bad Request

  • Unauthorized

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

Generate API key

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 /v1/user/apiKey

Request

Custom Headers

  • Authorization: Bearer <token>

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

Response

Successful API key response body

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Could not find the user associated with the Bearer token

  • Internal Server Error

Example responses
  • {
      "apiKey": "<api_key>",
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "_messageCode_": "authorization_fail",
      "message": "Not authorized. This action might require additional privileges or administrator permission.",
      "_statusCode_": 401
    }

Revoke API key

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

DELETE /v1/user/apiKey

Request

Custom Headers

  • Authorization: Bearer <token>

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

Response

Successful revoke API key response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Could not find the user associated with the Bearer token

  • Internal Server Error

Example responses
  • {
      "_messageCode_": "success",
      "message": "success"
    }

Log out

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

GET /v1/usermgmt/logout

Request

No Request Parameters

This method does not accept any request parameters.

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

Response

Status Code

  • Found. Redirecting to <url>

  • Unauthorized

No Sample Response

This method does not specify any sample responses.

Change logged in user's password

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 /v1/user/changemypassword

Request

Custom Headers

  • Authorization: Bearer <token>

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

Form Parameters

  • The new password.

    Example: newPassword

  • The current password.

    Example: currentPassword

  • 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

  • Unauthorized

  • Not Found

  • Success

No Sample Response

This method does not specify any sample responses.

Change a user's password

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 /v1/user/changeuserpassword

Request

Custom Headers

  • Authorization: Bearer <token>

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

Form Parameters

  • The user name.

    Example: username

  • The new password.

    Example: newPassword

  • 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

  • Unauthorized

  • Not Found

  • Success

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

Update current user profile

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

PUT /v2/own_profile

Request

Custom Headers

  • Authorization: Bearer <token>

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

Query Parameters

  • Flag to set theme for user profile.

    Example: true

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

Response

Successful setOwnProfile response body

Status Code

  • Success

  • Bad Request

  • Unauthorized

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

Get user groups

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

GET /v2/groups

Request

Custom Headers

  • Authorization: Bearer <token>

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

Query Parameters

  • Comma separated string of group identifiers.

    Example: 10000,10001

  • Comma separated string of role identifiers.

    Example: administrator,api_user

  • Set to true to include details about users in this group.

    Default: false

  • 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

List of user groups.

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • [
      {
        "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"
        ]
      }
    ]
  • {
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400,
      "exception": "Request validation failed: Parameter (include_members) is not a valid boolean: notABool"
    }

Create user group

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

POST /v2/groups

Request

Custom Headers

  • Authorization: Bearer <token>

    Examples:
    Authorization: Bearer <token>
    Authorization: ZenApiKey <token>
Examples:
default
  • 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

Status Code

  • Created

  • Bad Request

  • Unauthorized

  • Not Found

  • Conflict

  • Internal Server Error

Example responses
  • {
      "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"
    }
  • {
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400,
      "exception": "User-Group must have a name"
    }
  • {
      "_messageCode_": "authorization_fail",
      "message": "Not authorized. This action may require additional privileges or the administrator permission",
      "_statusCode_": 401
    }
  • {
      "_messageCode_": "conflict_error",
      "message": "Request conflicts with the current state of the server",
      "_statusCode_": 409,
      "exception": "Another usergroup with the same name exists."
    }
  • {
      "_messageCode_": "internal_error",
      "message": "Internal server error",
      "_statusCode_": 500,
      "exception": "duplicate key value violates unique constraint \"user_group_roles_group_id_role_id_key\""
    }

Update user group

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

PATCH /v2/groups/{group_id}

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • Unique ID indentifying the User-Group.

    Example: 10001

Examples:
default
  • curl -k -X PATCH 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{
      "name": {name},
      "description": {description},
      "account_id": {account_id},
      "add_role_identifiers": {add_role_identifiers},
      "remove_role_identifiers": {remove_role_identifiers}
    }'
    

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

  • Conflict

  • Internal Server Error

Example responses
  • {
      "group_id": 10001,
      "message": "success",
      "_messageCode_": "success"
    }
  • {
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400,
      "exception": "Request contains invalid role identifiers."
    }
  • {
      "_messageCode_": "authorization_fail",
      "message": "Not authorized. This action may require additional privileges or the administrator permission",
      "_statusCode_": 401
    }
  • {
      "_messageCode_": "conflict_error",
      "message": "Request conflicts with the current state of the server",
      "_statusCode_": 409,
      "exception": "Another usergroup with the same name exists."
    }
  • {
      "_messageCode_": "internal_error",
      "message": "Internal server error",
      "_statusCode_": 500,
      "exception": "duplicate key value violates unique constraint \"user_group_roles_group_id_role_id_key\""
    }

Delete user group

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

DELETE /v2/groups/{group_id}

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • Unique ID indentifying the User-Group.

    Example: 10001

  • curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
    

Response

Status Code

  • Created

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "group_id": 10001,
      "message": "success",
      "_messageCode_": "success"
    }
  • {
      "_messageCode_": "authorization_fail",
      "message": "Not authorized. This action may require additional privileges or the administrator permission",
      "_statusCode_": 401
    }
  • {
      "_messageCode_": "not_found",
      "message": "The asset is not found",
      "_statusCode_": 404,
      "exception": "User-Group not found"
    }

Get group members

This API allows users to view details about users associated with a certain group.

GET /v2/groups/{group_id}/members

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • User-Group identifier

    Example: 10001

Query Parameters

  • True if user_details are required in response

    Default: false

  • Offset required for pagination

  • Max number of records to return in a page

    Example: 25

  • Sorting the user records based upon specific column

    Allowable values: [uid,username,displayName,email]

    Default: uid

    Example: uid

  • Sorting order either ascending or descending

    Allowable values: [ASC,DESC]

    Default: DESC

    Example: DESC

  • curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/members?include_user_details={include_user_details}&offset={offset}&limit={limit}&sort_by={uid}&sort_order={sort_order}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
    

Response

Successful GET group members response body

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "results": [
        {
          "uid": "1000331141"
        },
        {
          "uid": "1000331114"
        },
        {
          "uid": "1000330999"
        }
      ],
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400,
      "exception": "Request validation failed: Parameter (group_id) is not a valid number: notAGroupId"
    }

Add members to a group

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

POST /v2/groups/{group_id}/members

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • User-Group identifier.

    Example: 10001

Payload containing LDAP groups and/or UIDs.

  • curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/members' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{
      "ldap_groups": {ldap_groups},
      "user_identifiers": {user_identifiers}, 
      "attribute_rules": {attribute_rules}
    }'
    

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "group_id": 10001,
      "message": "success",
      "_messageCode_": "success"
    }
  • {
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400,
      "exception": "Request validation failed: Parameter (group_id) is not a valid number: notAGroupId"
    }
  • {
      "exception": "User-Group not found",
      "_messageCode_": "not_found",
      "message": "The asset is not found",
      "_statusCode_": 404
    }

Delete group member

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

DELETE /v2/groups/{group_id}/members/{uid}

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • User-Group identifier.

    Example: 10001

  • The user's unique identifier.

    Example: 1000331015

  • curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/members/{uid}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
    

Response

Status Code

  • Success

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "group_id": 10001,
      "user_id": 1000331015,
      "message": "success",
      "_messageCode_": "success"
    }
  • {
      "_messageCode_": "member_undeletable",
      "message": "No members based on the provided criteria can be removed.",
      "_statusCode_": 404,
      "exception": "member_undeletable"
    }

Get group membership rules

This API allows users to view membership rule details for a group.

Membership rules define who can be a member of a group.

For example, the group membership rule 'uid=1000330999' states that the user with UID 1000330999 is a member of that group.

Similarly, the rule 'ldapGroup="CN=marketing,DC=ibm,DC=com"' states that all users in the LDAP group with that distinguished name (DN) are members of this group.

GET /v2/groups/{group_id}/membership_rules

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • User-Group identifier.

    Example: 10001

  • curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/membership_rules' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
    

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "message": "success",
      "results": {
        "rule_id": "123",
        "uid": 1000331015
      },
      "_messageCode_": "success"
    }
  • {
      "message": "success",
      "results": {
        "rule_id": "123",
        "logical_operator": "or",
        "realm_name": "usermgmt_default",
        "uid": 1000331015,
        "rules": [
          {
            "attribute": "location",
            "operator": "equal",
            "value": "US"
          },
          {
            "attribute": "organization",
            "operator": "equal",
            "value": "IBM"
          }
        ]
      },
      "_messageCode_": "success"
    }
  • {
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400,
      "exception": "Request validation failed: Parameter (group_id) is not a valid number: notAGroupId"
    }

Update membership rule

This API allows a user with an administrator role to update a membership rule via its ID.

PUT /v2/groups/membership_rules/{rule_id}

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • Rule identifier.

    Example: 123

Payload containing group membership rules.

Examples:
default
  • curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v2/groups/membership_rules/{rule_id}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{
      "realm_name": {realm_name},
      "logical_operator": {logical_operator},
      "rules": {rules}
    }'
    

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "message": "success",
      "rule_id": 123,
      "_messageCode": "success"
    }
  • {
      "exception": "Request validation failed: Parameter (body) failed schema validation",
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400
    }

Delete membership rule

This API allows a user with an administrator role to delete a membership rule via its ID.

DELETE /v2/groups/membership_rules/{rule_id}

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • Rule identifier.

    Example: 123

  • curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v2/groups/membership_rules/{rule_id}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
    

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "rule_id": 123,
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "exception": "Request validation failed: Parameter (rule_id) is not a valid number: notARuleId",
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400
    }
  • {
      "exception": "Membership Rule could not be found",
      "_messageCode_": "not_found",
      "message": "The asset is not found",
      "_statusCode_": 404
    }

Get LDAP users

This API allows users to view and filter a list of LDAP users.

POST /v2/ldap/users

Request

Custom Headers

  • Authorization: Bearer <token>

    Examples:
    Authorization: Bearer <token>
    Authorization: ZenApiKey <token>
Examples:
View
  • curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/ldap/users' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{
      "search_field": {search_field},
      "search_string": {search_string},
      "limit": {limit}
    }'
    

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • [
      {
        "dn": "",
        "username": "Administrator",
        "firstName": "",
        "lastName": "",
        "displayName": "",
        "email": "",
        "ldap_groups": [
          "CN=Group Policy Creator Owners,CN=Users,DC=wdp,DC=com",
          "CN=Domain Admins,CN=Users,DC=wdp,DC=com",
          "CN=Enterprise Admins,CN=Users,DC=wdp,DC=com",
          "CN=Schema Admins,CN=Users,DC=wdp,DC=com",
          "CN=Administrators,CN=Builtin,DC=wdp,DC=com"
        ],
        "realmName": "testConn1",
        "formattedName": "",
        "extAttributes": {}
      }
    ]
  • {
      "_messageCode_": "browse_ldap_fail",
      "message": "Failed to browse LDAP server.",
      "_statusCode_": 400,
      "exception": "Missing required parameter"
    }

Get LDAP groups

This API allows users to view and filter a list of LDAP groups.

POST /v2/ldap/groups

Request

Custom Headers

  • Authorization: Bearer <token>

    Examples:
    Authorization: Bearer <token>
    Authorization: ZenApiKey <token>
Examples:
View
  • curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/ldap/groups' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{
      "search_string": {search_string},
      "limit": {limit}
    }'
    

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • [
      {
        "dn": "CN=Administrators,CN=Builtin,DC=wdp,DC=com",
        "name": ""
      }
    ]
  • {
      "_messageCode_": "browse_ldap_fail",
      "message": "Failed to browse LDAP server.",
      "_statusCode_": 400,
      "exception": "Missing required parameter"
    }

Get all roles

This API allows users to view and filter a list of role details, including values such as permissions associated with the role.

GET /v1/roles

Request

Custom Headers

  • Authorization: Bearer <token>

    Examples:
    Authorization: Bearer <token>
    Authorization: ZenApiKey <token>
  • Pass language for translated content.

    Example: en-US

Query Parameters

  • Set to true to return count of users assigned to each role.

    Default: false

  • Set to true to return count of platform users assigned to each role individually.

    Default: false

  • Set to true to return count of user-groups assigned to each role.

    Default: false

  • curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/roles?include_users_count={include_users_count}&include_platform_users_count={include_platform_users_count}&include_user_groups_count={include_user_groups_count}' -H 'Accept-Language: en-US' -H 'Authorization: Bearer {token}'
    

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

Example responses
  • {
      "rows": [
        {
          "id": "4ebdc848-8259-46de-8696-0ce43473cf73",
          "key": "4ebdc848-8259-46de-8696-0ce43473cf73",
          "doc": {
            "_id": "4ebdc848-8259-46de-8696-0ce43473cf73",
            "extension_id": "_ce_770289729567424515",
            "extension_name": "4ebdc848-8259-46de-8696-0ce43473cf73",
            "role_name": "Example",
            "description": "Example role.",
            "permissions": [
              "manage_vaults_and_secrets"
            ],
            "updated_at": 1652663415565
          }
        }
      ],
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "rows": [
        {
          "id": "4ebdc848-8259-46de-8696-0ce43473cf73",
          "key": "4ebdc848-8259-46de-8696-0ce43473cf73",
          "doc": {
            "_id": "4ebdc848-8259-46de-8696-0ce43473cf73",
            "extension_id": "_ce_770289729567424515",
            "extension_name": "4ebdc848-8259-46de-8696-0ce43473cf73",
            "role_name": "Example",
            "description": "Example role.",
            "permissions": [
              "manage_vaults_and_secrets"
            ],
            "updated_at": 1652663415565,
            "users_count": 3
          },
          "platform_users_count": 42,
          "user_groups_count": 7
        }
      ],
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "rows": [
        {
          "id": "4ebdc848-8259-46de-8696-0ce43473cf73",
          "key": "4ebdc848-8259-46de-8696-0ce43473cf73",
          "doc": {
            "_id": "4ebdc848-8259-46de-8696-0ce43473cf73",
            "extension_id": "_ce_770289729567424515",
            "extension_name": "4ebdc848-8259-46de-8696-0ce43473cf73",
            "role_name": "Example",
            "description": "Example role.",
            "permissions": [
              "manage_vaults_and_secrets"
            ],
            "updated_at": 1652663415565,
            "users_count": 3
          }
        }
      ],
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "rows": [
        {
          "id": "4ebdc848-8259-46de-8696-0ce43473cf73",
          "key": "4ebdc848-8259-46de-8696-0ce43473cf73",
          "doc": {
            "_id": "4ebdc848-8259-46de-8696-0ce43473cf73",
            "extension_id": "_ce_770289729567424515",
            "extension_name": "4ebdc848-8259-46de-8696-0ce43473cf73",
            "role_name": "Example",
            "description": "Example role.",
            "permissions": [
              "manage_vaults_and_secrets"
            ],
            "updated_at": 1652663415565
          },
          "platform_users_count": 42
        }
      ],
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "rows": [
        {
          "id": "4ebdc848-8259-46de-8696-0ce43473cf73",
          "key": "4ebdc848-8259-46de-8696-0ce43473cf73",
          "doc": {
            "_id": "4ebdc848-8259-46de-8696-0ce43473cf73",
            "extension_id": "_ce_770289729567424515",
            "extension_name": "4ebdc848-8259-46de-8696-0ce43473cf73",
            "role_name": "Example",
            "description": "Example role.",
            "permissions": [
              "manage_vaults_and_secrets"
            ],
            "updated_at": 1652663415565
          },
          "user_groups_count": 7
        }
      ],
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400,
      "exception": "Request validation failed: Parameter (include_users_count) is not a valid boolean: notABool"
    }

Add new role

This API allows users with an administrator role to add a new role.

POST /v1/role

Request

Custom Headers

  • Authorization: Bearer <token>

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

Create role object.

Examples:
default
  • curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/role' -H 'Authorization: Bearer {token}' -H 'Content-Type: application/json' -d '{
      "description": {description},
      "permissions": {permissions}
    }'
    

Response

Status Code

  • Created

  • Bad Request

  • Unauthorized

  • Not Found

Example responses
  • {
      "id": "a8c524f6-f8d1-47b7-80b4-dc3d3c2abcdf",
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400,
      "exception": "Request validation failed: Parameter (body) failed schema validation"
    }
  • {
      "_messageCode_": "authorization_fail",
      "message": "Not authorized. This action might require additional privileges or administrator permission.",
      "_statusCode_": 401
    }

Update role record

This API allows users with an administrator role to update an existing role.

PUT /v1/role/{id}

Request

Custom Headers

  • Authorization: Bearer <token>

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

Path Parameters

  • Extension name of the role that needs to be updated.

    Example: 22c69856-3e21-4301-b83c-3b226e957d9e

Update role object.

Examples:
default
  • curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v1/role/{id}' -H 'Authorization: Bearer {token}' -H 'Content-Type: application/json' -d '{
      "role_name": {role_name},
      "description": {description},
      "permissions": {permissions}
    }'
    

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Not Found

Example responses
  • {
      "id": "22c69856-3e21-4301-b83c-3b226e957d9e",
      "message": "success",
      "_messageCode_": "success"
    }
  • {
      "_messageCode_": "bad_request",
      "message": "Payload is invalid",
      "_statusCode_": 400,
      "exception": "Request validation failed: Parameter (body) failed schema validation"
    }
  • {
      "_messageCode_": "authorization_fail",
      "message": "Not authorized. This action might require additional privileges or administrator permission.",
      "_statusCode_": 401
    }
  • {
      "_messageCode_": "updateRole_fail",
      "message": "Updating role failed",
      "_statusCode_": 404,
      "exception": "Could not parse role that was retrieved"
    }

Delete role record

This API allows users with an administrator role to delete an existing role.

DELETE /v1/role/{id}

Request

Custom Headers

  • Authorization: Bearer <token>

    Examples:
    Authorization: Bearer <token>
    Authorization: ZenApiKey <token>
  • Pass language for translated content.

    Example: en-US

Path Parameters

  • Extension name of the role that needs to be deleted.

    Example: 22c69856-3e21-4301-b83c-3b226e957d9e

  • curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v1/role/{id}' -H 'Accept-Language: en-US' -H 'Authorization: Bearer {token}'
    

Response

Status Code

  • Success

  • Unauthorized

  • Not Found

Example responses
  • {
      "id": "22c69856-3e21-4301-b83c-3b226e957d9e",
      "_messageCode_": "success",
      "message": "success"
    }
  • {
      "_messageCode_": "authorization_fail",
      "message": "Not authorized. This action might require additional privileges or administrator permission.",
      "_statusCode_": 401
    }
  • {
      "_messageCode_": "deleteRole_fail",
      "message": "Deleting role failed",
      "_statusCode_": 404,
      "exception": "Could not parse role that was retrieved"
    }

Get attributes

This API allows users to view attribute details from Zen's own attribute directory.

GET /v2/attributes

Request

Custom Headers

  • Authorization: Bearer <token>

    Examples:
    Authorization: Bearer <token>
    Authorization: ZenApiKey <token>
  • curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/attributes' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
    

Response

Status Code

  • Success

  • Unauthorized

Example responses
  • {
      "data": {
        "usermgmt_default": {
          "location": {
            "displayName": "Location",
            "attribute_type": "simple",
            "type": "string",
            "enabled": true,
            "internal_only": false,
            "path": "location"
          },
          "nationality": {
            "displayName": "Nationality",
            "attribute_type": "simple",
            "type": "string",
            "enabled": true,
            "internal_only": false,
            "path": "nationality"
          },
          "organization": {
            "displayName": "Organization",
            "attribute_type": "simple",
            "type": "string",
            "enabled": true,
            "internal_only": false,
            "path": "organization"
          },
          "userType": {
            "displayName": "User type",
            "attribute_type": "complex",
            "type": "string",
            "enabled": true,
            "internal_only": false,
            "path": "name.userType"
          }
        }
      },
      "_messageCode_": "get_configmap_attributes_success",
      "message": "get_configmap_attributes_success"
    }