IBM Cloud API Docs

Create and manage user accounts, user groups, roles, events, vaults, cards, and volumes on IBM® Cloud Pak for Data by 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 the Cloud Pak for Data platform.

You can perform the following tasks by 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 many 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 information, generating an API key, or changing their password.

A Cloud Pak for Data administrator with the administrator or manage_users permissions can also create, update, or delete user-profiles.

Manage service instances

A Cloud Pak for Data administrator with the Create service instances permission can create, retrieve, and delete service instances.

Configure monitors and alerts

A Cloud Pak for Data administrator can browse generated events and configure monitors and alerts.

Create custom cards for the home page

Administrators can create custom cards to display key performance indicators on the Cloud Pak® for Data home page.

Manage secrets and vaults

Authenticated users can safeguard credentials and secrets with access control and audit logging by using vaults.

Manage persistent volume instances

Administrators with the Create service instances permission can create and manage persistent volume instances on your existing Cloud Pak® for Data storage devices.

Authentication

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

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.

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 can call the Generate API key method. Note: this method must be called with bearer access token authorization.

When you get the API Key from the user experience or from the "generate API Key" method, you must Base64 encode <username>:<api_key> to get the token.

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.

Generating an access token by 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 by using an access token. Replace {token} with your details.

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

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

Generate the token by 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 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 was successful. 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_
String
An identifier of the response.
statusCode
Integer
The HTTP response code.
exception
String
An explanation of the problem.
message
String
An explanation of the _messageCode_.

Configuring monitors and alerts

You can browse generated events and configure monitors and alerts by using the Alerting APIs.

Required role: You must have administration privileges in Cloud Pak for Data. API authentication uses an authorization token with administration privileges.

Creating custom cards for the home page

You can create custom cards to display key performance indicators on the Cloud Pak® for Data home page with the Custom cards API.

Required role: You must have administration privileges in Cloud Pak for Data. API authentication uses an authorization token with administration privileges.

Cards give users access to recently used items and an overview of important changes and alerts. The list of available cards is determined by the services that are installed on the platform. You can also add custom cards to the home page with the custom cards API. You can prevent certain cards from being displayed on the home page by disabling them. Each user might see only a subset of the cards based on their permissions and the services that they have access to, so consider how disabling a card affects users with different roles.

You can start with a template to create each of the custom cards that are shown in the following image. See the template types for a description of the templates that were used.

Examples of template types
Figure 1. A collection that shows examples of custom cards

Template types:

  1. The donut template illustrates an array of values as percentages in a donut chart.
  2. The bartemplate creates a two-dimensional bar graph.
  3. The big_number template highlights significant data.
  4. The text_list displays a list of text strings.
  5. The number_list displays a list of numeric values and associated text.
  6. The list displays a list of navigation links. The list can contain headers and associated clickable links.
  7. The content_block displays rows of text or links. Each row can be a paragraph of text or clickable links.

Managing secrets and vaults

You can safeguard credentials and secrets with access control and audit logging by using the Vaults and secrets APIs.

Required role: An authorization token is generally created for a specific user ID. That user ID determines the permissions that are applied in the API calls. For example, the API returns only the content for those secrets that are visible to the particular user ID.

Security is critical when services use secrets such as database access credentials, SSL certificates, API keys, and authentication tokens. Customers are also subject to regulatory compliance, which means that they must report and audit privileged credential usage, and forensic analysis of access. If you store and access credentials in plain text on applications and services, you might incur a serious security risk. You need tools that provide access and secrets management, both for system identities and user identities.

The Vaults and secrets APIs provide a centralized mechanism that is hardened by data encryption, secure access control, authorization checks, and auditing. You can securely store and tightly control access to secrets (such as passwords, tokens, API keys, encryption keys, and certificates) to protect access to sensitive data. You can store credentials such as passwords, API keys, tokens, certificates, or other sensitive information within a vault.

You can also manage credentials and secrets by using the user interface. For more information, see Managing secrets and vaults.

You can also access vaults by using Python in Notebooks, scripts, and other code to store and retrieve secrets. For more information, see the IBM CPD Core Python Client.

Managing persistent volume instances

You can create and manage persistent volume instances on your existing Cloud Pak® for Data storage devices with the Volumes APIs.

Required role: To use this API, you must have the Create service instances permission in Cloud Pak for Data. You can check which permissions you have from your profile.

Many enterprise applications use a mounted file system to work with data sets. For example, many Spark jobs process CSV, PARQUET, and AVRO files that are stored on a POSIX-compliant shared file system that can be accessed by all of the executors. However, you might need to store source code for Spark jobs or other packages that can be used by your Spark jobs. In some cases, these additional files need to be stored on a mountable, shared file system. You can use a volume instance to store these files by using the Volumes API.

You can perform the following tasks:

Work directly with the files on the file system

You can use the managed volume instances to host files. You can give Cloud Pak for Data users access to the volume instance, and the volume instance can be accessed by services that are running on Cloud Pak for Data.

With the Volumes API, you can create persistent volumes without direct access to Kubernetes or in-depth knowledge of Kubernetes storage principles. However, you should have a basic understanding of Kubernetes storage concepts.

Store and access files that are generated by other services in your ecosystem

The volume instance is created through a Red Hat® OpenShift® storage account in the Cloud Pak for Data project (namespace) on behalf of the users who creates the volume instance.

After a volume instance is created, you can associate (mount) the volume in the appropriate pods in your Cloud Pak for Data deployment.

Enable access management for specific volumes

You can specify which users have access to the volume instance to ensure that only authorized users have access to the volume. Important: A user with direct access to Kubernetes and sufficient privileges on the storage device can potentially still access a volume instance that was created by using the Volumes API.

Allow authorized users to use the Volume API to upload files into their volumes

Authorized users can upload, view, or delete files on the volume by using the Volumes API and its utilities.

Versioning

This documentation describes the APIs that are available in the current refresh of Cloud Pak for Data 4.8.x.

Change log

The Cloud Pak for Data Platform 4.8.0 API now includes the following methods and examples:

  • Service instance APIs to create, retrieve, and delete services instances

Methods

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 configuration info

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

GET /usermgmt/v1/usermgmt/config

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v1/usermgmt/config

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v1/preauth/validateConfig

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 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 /usermgmt/v1/usermgmt/users

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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 through 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: ZenApiKey {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 /usermgmt/v1/usermgmt/user/{uid}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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.

The email field must be unique. An error code 400 will be returned if the email address is already in use.

POST /usermgmt/v1/user

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {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' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {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 /usermgmt/v1/users

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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.

The email field must be unique. Any user who has the email address that is already in use will not get access granted.

POST /usermgmt/v1/user/bulk

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v1/user/currentUserInfo

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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.

The email field must be unique. An error code 400 will be returned if the email address is already in use.

PUT /usermgmt/v1/user/{username}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {TOKEN}' -d '{
      "displayName":{displayName},
      "email":{email},
      "username":{username},
      "user_roles":{user_roles}
    }'
    

Response

Status Code

  • Success.

  • Bad Request.

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

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 token and session cookie.

POST /usermgmt/v1/user/renewToken

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v1/user/apiKey

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Response

Successful API key response body.

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Could not find the user associated with the 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 /usermgmt/v1/user/apiKey

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Response

Successful revoke API key response.

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Could not find the user associated with the token.

  • Internal Server Error.

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

Log out

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.

  • curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/logout' -H 'Authorization: ZenApiKey {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 /usermgmt/v1/user/changemypassword

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v1/user/changeuserpassword

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/own_profile

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/groups

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/groups

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/groups/{group_id}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/groups/{group_id}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/groups/{group_id}/members

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/groups/{group_id}/members

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/groups/{group_id}/members/{uid}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/groups/{group_id}/membership_rules

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/groups/membership_rules/{rule_id}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/groups/membership_rules/{rule_id}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/ldap/users

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
Examples:
View
  • curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/ldap/users' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {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 /usermgmt/v2/ldap/groups

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
Examples:
View
  • curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/ldap/groups' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {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 /usermgmt/v1/roles

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v1/role

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Create role object.

Examples:
default
  • curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/role' -H 'Authorization: ZenApiKey {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 /usermgmt/v1/role/{id}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v1/role/{id}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <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: ZenApiKey {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 /usermgmt/v2/attributes

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Create a service instance

Creates a service instance. You must include the service instance definition as a JSON string in the HTTP request body. Can be initiated only by a user with the Create service instances permission.

POST /v3/service_instances

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

ServiceInstance metadata artifact that must be added to the database.

Examples:
/v3/service_instances
  • curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "addon_type": "volumes",
          "addon_version": "-",
          "create_arguments": {
            "metadata": {
              "volume_type": "NEW_PVC",
              "storageClass": "nfs-client",
              "storageSize": "1Gi",
              "mount_path": "<mount-path>"
            }
            },
          "namespace": "zen",
          "display_name": "volumes-sample-1"
        }'
    
  • curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "addon_type": "volumes",
          "addon_version": "-",
          "create_arguments": {
            "metadata": {
              "volume-type": "EXISTING_PVC",
              "existing_pvc_name": "user-home-pvc",
              "supplemental_groups": [8888, 1111]
              "mount_path": "<mount-path>"
            }
            },
          "namespace": "zen",
          "display_name": "existing-pv-sample-1"
        }'
    
  • curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "addon_type": "volumes",
          "addon_version": "-",
          "create_arguments": {
            "metadata": {
              "volume_type": "EXTERNAL_NFS",
              "nfs_server_address": "9.30.10.10",
              "nfs_export_path": "/mnt/nfs_shares/",
              "mount_path": "/mnts/data/"
              "supplemental_groups": [8888, 1111]
            }
            },
          "namespace": "<control-plane-namespace>",
          "display_name": "<display-name>"
        }'
    
  • curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "addon_type": "volumes",
          "addon_version": "-",
          "create_arguments": {
            "metadata": {
              "volume_type": "SMB_CIFS",
              "cifs_server_address": "9.30.94.140",
              "cifs_export_path": "private",
              "mount_path": "/mnts/samba",
              "cifs_username": "admin"
            }
          },
          "namespace": "zen",
          "display_name": "samba-doc-test",
          "transient_fields": {
            "cifs_password": "password"
          }
        }'
    
  • curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "addon_type": "volumes",
          "addon_version": "-",
          "create_arguments": {
            "metadata": {
              "storageClass": "<storage-class>",
              "storageSize": "<space-allocated-to-volume>",
              "file_server": {
                "start": true,
                "resources": {
                  "limits": {
                    "cpu": "<cpu-limits>",
                    "memory": "<memory-limits>"
                  },
                  "requests": {
                    "cpu": "<cpu-requests>",
                    "memory": "<memory-requests>"
                  }
                }
              }
            }
          },
          "namespace": "<control-plane-namespace>",
          "display_name": "<display-name>"
        }'
    
  • curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "addon_type": "ez-addon-app",
          "addon_version": "1.0.0.0",
          "create_arguments": {
            "description": "string",
            "metadata": {
              "NGINX_TIMEOUT": "10"
            },
            "parameters": {}
          },
          "display_name": "<display-name>",
          "pre_existing_owner": false,
          "transient_fields": {}
        }'
    

Response

Status Code

  • Success.

  • Accepted.

  • Bad Request.

  • Forbidden.

  • Conflict.

  • Precondition Failed.

  • Internal Server Error.

  • Gateway Timeout.

Example responses
  • {
      "id": 1585361220129
    }

Get a service instance collection

Retrieves the list of service instances that you have access to.

GET /v3/service_instances

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Query Parameters

  • If set to true returns all service instances. This parameter can be used by an Administrator only.

  • Type of the add-on.

  • Exclude addon type volumes in the collection.

    Default: false

  • Version of the add-on, this parameter must be used with the addon_type parameter.

  • Name of the instance to query.

  • Category of the add-on, this cannot be used with other parameters.

  • The number of service instances to skip before starting to collect the result set.

  • The number of service instances to return.

    Example: 20

  • # Retrieve service instances
    curl -k -X GET 'https://{HOSTNAME}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    
    # Retrieve service instances with addon_type=volumes
    curl -k -X GET 'https://{HOSTNAME}/v3/service_instances?addon_type=volumes' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get service instance details

Returns the details of the service instance.

GET /v3/service_instances/{instance_id}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

  • Language that the add-on placeholder strings such as short and long description will be returned in.

    Default: en

Path Parameters

  • service instance identifier

Query Parameters

  • If true service status is retrieved from the provider.

    Default: false

  • curl -k -X GET 'https://{cpd_cluster_host}/v3/service_instances/{instance_id}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Conflict.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Delete a service instance

Deletes a service instance and removes users' access to the service instance. Important: The data inside the volume is not deleted and services can continue to use the volume until a Red Hat OpenShift project administrator removes the persistent volume claim to reclaim the storage. The reclaim policy that is specified in the storage class determines what happens when the persistent volume claim is deleted.

DELETE /v3/service_instances/{instance_id}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • Service Instance Identifier

Query Parameters

  • Set to true if the instance must be force deleted and bypass the default defensive checks pertaining to the service status.

  • curl -k -X DELETE 'https://{cpd_cluster_host}/v3/service_instances/{instance_id}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Accepted.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Conflict.

  • Precondition Failed.

  • Internal Server Error.

  • Gateway Timeout.

No Sample Response

This method does not specify any sample responses.

View all events

Returns a list of events that are recorded by the monitor and associated event type. The historical data for each event lists severity of the referenced resource at the time the monitor cron job collected its state. This list can be filtered to return only events of a specific severity.

GET /zen-watchdog/v1/monitoring/events

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • curl -k -X GET 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/events' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Delete monitoring events

Deletes monitoring events that are older than the specified number of days.

POST /zen-watchdog/v1/monitoring/events/prune

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Query Parameters

  • Number of days to retain.

    Default: 3

  • curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/events/prune?retention_time={retention_time}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad request.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Delete metrics records

Deletes metrics records that are older than the specified number of days.

POST /zen-watchdog/v3/metrics/prune

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Query Parameters

  • Number of days to retain.

    Default: 30

  • curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v3/metrics/prune?retention_time={retention_time}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad request.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Configure email recipients

Configures alerts to be sent as email. You can configure a connection to your SMTP server in Administration > Platform configuration.

PATCH /zen-watchdog/v1/monitoring/config/smtp

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

SMTP config for alert monitoring.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/smtp' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}'  -d '{
            “registered_emails” : [{registered_emails}]
        }'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Not Found.

  • Conflict.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

View alerted events

Returns a list of events by monitor that have promoted alerts and are currently in the snooze period, which can be further filtered by a specific event type.

GET /zen-watchdog/v1/monitoring/getAlertedEvents

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Query Parameters

  • The name of the monitor. The default monitor is diagnostics.

  • Event type, which is used along with the monitor_type. The following event types are delivered with Cloud Pak for Data: check-pvc-status (records a critical event if a PVC is unbound), check-replica-status (records a critical event if a StatefulSet or deployment has unavailable replicas), check-resource-status (records a warning event if a service has reached the threshold and a critical event if it has exceeded the quota).

  • curl -k -X GET 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/getAlertedEvents' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Configure monitor schedule

Updates the schedule for the diagnostics monitor or a custom monitor. Monitors must be scheduled as a cron job. By default, the cron job for the default monitor, diagnostics, is scheduled to run every 10 minutes.

PATCH /zen-watchdog/v1/monitoring/config/monitorType

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Query Parameters

  • The name of the monitor. The default monitor is diagnostics.

Configure zen alert monitor.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/monitorType' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{
            “schedule” : ”*/10 * * * *”
        }'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Not Found.

  • Conflict.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Configure event type

Allows you to edit configuration details for a particular event type for a monitor.

PATCH /zen-watchdog/v1/monitoring/config/eventType

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Query Parameters

  • The name of the monitor. The default monitor is diagnostics.

  • Event type. The following event types are delivered with Cloud Pak for Data: check-pvc-status (records a critical event if a PVC is unbound), check-replica-status (records a critical event if a StatefulSet or deployment has unavailable replicas), check-resource-status (records a warning event if a service has reached the threshold and a critical event if it has exceeded the quota).

Event config.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/eventType' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{
          <body_params>
      }'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Not Found.

  • Configuration Settings Invalid.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Configure alert rules

Configures rules for critical and warning events, including the snooze period and whether an alert is needed when an incident corrects itself.

PATCH /zen-watchdog/v1/monitoring/config/alertType

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Query Parameters

  • Name of the alert type. The default alert_type is platform.

  • The severity for which the rules need to be updated. One of the following options: critcal, warning. You can't configure the alert rules for informational alerts.

    Allowable values: [critical,warning]

  • Event type.

Event config.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/alertType' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{
          <body_params>
      }'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Not Found.

  • Configuration Settings Invalid.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get SNMP configuration

Retrieves the current SNMP configuration.

GET /zen-watchdog/v1/monitoring/config/snmp

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • curl -k -X GET 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/snmp' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Config Not Found.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Configure SNMP

Configures alerts to be sent as traps by using SNMP (simple network management protocol). SNMP is a standard protocol for collecting and organizing information about managed devices or services. It exposes management data in the form of variables that are defined in managed information base (MIB) files. Use GET to retrieve the current SNMP configuration. Use POST to update the SNMP configuration.

POST /zen-watchdog/v1/monitoring/config/snmp

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Form Parameters

  • The SNMP server host address.

  • The community string associated with the SNMP connection.

  • The SNMP server port.

  • curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/snmp' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Unauthorized.

  • Not Found.

  • Configuration Settings Invalid.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get Slack configuration

Retrieves the current Slack configuration.

GET /zen-watchdog/v1/monitoring/config/slack

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • curl -k -X GET 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/slack' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Configuration Not Found.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Configure Slack

Configures alerts to be set as messages in a Slack channel. To enable Slack alerts, an administrator must provide a webhook URL, which can be set up to receive notifications on a channel. Use GET to retrieve the current Slack configuration. Use POST to update the Slack webhook URL.

POST /zen-watchdog/v1/monitoring/config/slack

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Form Parameters

  • The URL of the webhook to post to a Slack channel.

  • curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/slack' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Unauthorized.

  • Not Found.

  • Configuration Settings Invalid.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get a list of monitors, profiles, or alert types

Lists all registered monitors and associated event types. The default monitor is diagnostics. Lists all alert types or rules, which define when alerts need to send. The default alert type is platform. Lists all registered alert profiles to enable or disable a certain type of alert (SMTP, SNMP, or Slack). Also provides metadata for the alert methods, including the list of email addresses that are registered to receive alerts.

GET /v1/extensions

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

    Example: en-US

Query Parameters

  • Set to zen_alert_monitor to get a list of monitors. Set to zen_alert_type to get a list of alert types.

  • Identifier of a particular extension.

  • Array of particular extensions' names.

  • Type of preference.

    Allowable values: [global,user]

    Default: user

  • Identifier for a particular source.

  • Query parameter when disabled will return the disabled extensions.

    Default: enabled

  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/extensions?extension_point_id=zen_alert_monitor' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    
  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/extensions?extension_point_id=zen_alert_type' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    
  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/extensions?extension_point_id=zen_alert_profile' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get a list of custom cards

Retrieves the properties for the custom cards that you can update.

GET /v1/custom_cards

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/custom_cards' -H 'Accept-Language: en-US' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

Example responses
  • {
      "_messageCode_": "success",
      "message": "Successfully retrieved custom cards",
      "data": {}
    }

Create or replace a custom card

Creates a custom card or replaces an existing custom card. You must include the card definition as a JSON string in the HTTP request body. The definition specifies the structure and the content of the card.

PUT /v1/custom_cards/{key}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • The name of the card that you want to create or replace. The string must be unique. If a custom card with the specified key does not exist, the custom card is created, otherwise the existing custom card is replaced.

Update role object.

  • curl -k -X PUT 'https://{cpd_cluster_host}/zen-data/v1/custom_cards' -H 'Accept-Language: en-US' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
        "permissions": ["manage_catalog"],
        "order": 1,
        "title": "Disk usage",
        "template_type": "big_number",
        "data": {      "big_number_data": {
              "metric":  "55",
              "sub_text": "Increase since last month",
              "prefix": "ArrowUp32",
              "suffix": "%",
              "footer_1": "867 Total vulnerabilities",
              "footer_2": "AskPQL 2.3 package most at risk"
            }
          }
      }'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

Example responses
  • {
      "_messageCode_": "success",
      "data": {
        "id": 537163840404062200,
        "name": "os_vulnerabilities",
        "title": "Open source vulnerabilities",
        "description": "",
        "drilldown_url": "",
        "order": 12,
        "template_type": "big_number",
        "data_url": "",
        "empty_state": {},
        "source_url": "",
        "refresh_rate": 0,
        "data": {
          "big_number_data": {
            "metric": 55,
            "sub_text": "Increase since last month",
            "prefix": "ArrowUp32",
            "suffix\"": "%",
            "footer_1": "867 Total vulnerabilities",
            "footer_2": "AskPQL 2.3 package most at risk"
          }
        }
      }
    }

Update an existing card

Updates the information that is displayed on an existing card.

PATCH /v1/custom_cards/{key}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • The name of the card that you want to update.

Update role object.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/v1/custom_cards/disk_usage_donut' -H 'Accept-Language: en-US' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
        "title": "Disk usage"
      }'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

Example responses
  • {
      "_messageCode_": "success",
      "message": "Successfully edited custom card",
      "data": {
        "id": 1,
        "name": "homepage_card_disk_usage",
        "title": "Disk usage",
        "description": "",
        "drilldown_url": "/zen/#/v1/diskUsage",
        "order": 2,
        "template_type": "donut",
        "data_url": "/v1/homepage/diskUsage",
        "empty_state": {},
        "source_url": "",
        "refresh_rate": 0,
        "data": null
      }
    }

Delete a custom card

Deletes an existing card with the specified key.

DELETE /v1/custom_cards/{key}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • The name of the custom card that you want to delete.

  • curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v1/custom_cards/os_vulnerabilities' -H 'Accept-Language: en-US' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

Example responses
  • {
      "_messageCode_": "success",
      "message": "Successfully deleted custom card"
    }

Store an external vault configuration

Creates an external vault integration by using this API.

POST /v2/vaults

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Query Parameters

  • Validate vault connection.

    Default: false

  • Validate vault connection and save.

    Default: false

Sensitive payload to be secured.

Examples:
/v2/vaults
  • curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/vaults' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "description": "This is cyberark aam vault",
          "details": {
          "vault_address": "https://vault.myorg.com:14506",
          "app_id": "testappid",
          "client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQprZXkKLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0K",
          "client_certificate" : "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCmNlcnQKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQoK"
          },
          "type": "cyberark_aam_cert",
          "vault_name": "My-cyberarkaam-vault"
      }'
    

Response

Status Code

  • Success.

  • Test connection success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Conflict.

  • Internal Server Error.

Example responses
  • {
      "vault_urn": "1000330999:My-cyberarkaam-vault"
    }

Retrieve details about external vault integrations

Retrieves details about external vault integrations for user.

GET /v2/vaults

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Query Parameters

  • The number of vaults to skip before starting to collect the result set.

    Default: 0

  • The number of vaults to return.

    Default: 50

  • Preview secrets.

    Default: false

  • Sort by the field (such as sort=display_name or sort=-display_name for descending). The supported sort columns are: vault_name, owned_by, created_by, uploaded_at, total_secrets.

  • Comma-separated provider names (such as CyberArk AAM, HashiCorp).

  • A name for your vault. This name must be unique across all the vaults that you own and that are currently stored in the vault.

  • Match on all or any criteria, possible values.

    Allowable values: [any,all]

    Default: any

  • If true, returns all vaults when user has manage vaults permission.

    Default: false

  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/vaults?limit=2&sort=updated_at&provider_name=cyber,hashi' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

Example responses
  • {
      "limit": 2,
      "offset": 0,
      "total_count": 4,
      "vaults": [
        {
          "created_at": "2021-05-18T02:19:37.237302Z",
          "created_by": "admin",
          "description": "creating sample vault test-hashicorp-token-vault-0",
          "invalid_auth": false,
          "invalid_owner": false,
          "owned_by": "admin",
          "provider_name": "Hashicorp - Token Authentication",
          "secret_preview": "test-hashicorp-token-vault-0-secret-0",
          "total_secrets": 1,
          "updated_at": "2021-05-18T02:19:37.23523Z",
          "vault_name": "test-hashicorp-token-vault-0",
          "vault_type": "hashicorp_token",
          "vault_urn": "1000330999:test-hashicorp-token-vault-0"
        },
        {
          "created_at": "2021-05-18T02:19:37.258828Z",
          "created_by": "admin",
          "description": "creating sample vault test-cyberark-aam-cert-vault-0",
          "invalid_auth": false,
          "invalid_owner": false,
          "owned_by": "admin",
          "provider_name": "CyberArk AAM - Cert Authentication",
          "secret_preview": "test-cyberark-aam-cert-vault-0-secret-0",
          "total_secrets": 1,
          "updated_at": "2021-05-18T02:19:37.257123Z",
          "vault_name": "test-cyberark-aam-cert-vault-0",
          "vault_type": "cyberark_aam_cert",
          "vault_urn": "1000330999:test-cyberark-aam-cert-vault-0"
        }
      ]
    }

Retrieve a vault

Retrieves the details for a vault that is specified by the vault's uniform resource name.

GET /v2/vaults/{vault_urn}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • The vault identifier. This parameter uses a specific notation: <creator uid>:<vault_name>.

  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/vaults/<vault_urn>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Update external vault configuration

Updates configuration details of an external vault, response does not includes sensitive data.

PATCH /v2/vaults/{vault_urn}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • The vault identifier. This parameter uses a specific notation: <creator uid>:<vault_name>.

Query Parameters

  • Validate vault connection.

    Default: false

  • Validate vault connection and save.

    Default: false

Sensitive payload to be secured.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/v2/vaults/<vault_urn>' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{
        "description": "<description>",
        "details": <details>,
        "test_data": <test-data>
      }'
    

Response

Status Code

  • Success.

  • Test connection success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Delete external vault integration

Deletes a specific external vault integration for user. Note: Deleting a vault deletes all of its associated secrets.

DELETE /v2/vaults/{vault_urn}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • The vault identifier. This parameter uses a specific notation: <creator uid>:<vault_name>.

  • curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v2/vaults/<vault_urn>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Initiate the transfer of ownership of a vault

Initiates the transfer of ownership of a vault and any secrets in the vault to a different owner.

POST /v2/vaults/{vault_urn}/transfers

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • The vault identifier. This parameter uses a specific notation: <creator uid>:<vault_name>.

Query Parameters

  • If true, transfer re-submission will be executed only if allowed transfer duration is over.

    Default: false

Sensitive payload to be secured.

  • curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/vaults/<vault-urn>/transfers' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          new_owner_uid": "1000331007"
      }'
    

Response

Status Code

  • Success.

  • Transfer vault request accepted.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Conflict.

  • Internal Server Error.

Example responses
  • {
      "value": {
        "metadata": {
          "created_at": "2022-02-24T21:36:45.677Z",
          "created_by": "user4",
          "description": "Create HashiCorp vault for transferring vault ownership tests synchronously.",
          "invalid_auth": true,
          "invalid_owner": false,
          "owned_by": "user7",
          "owner_uid": 1000331007,
          "provider_name": "Hashicorp",
          "secret_preview": "vault-hashi-uc-trans-vault-secret-1vault-hashi-uc-trans-vault-secret-2vault-hashi-uc-trans-vault-secret-3",
          "total_secrets": 3,
          "updated_at": "2022-02-24T21:36:45.677Z",
          "vault_name": "vault-hashi-uc-trans-vault",
          "vault_type": "hashicorp_token",
          "vault_urn": "1000331031:vault-hashi-uc-trans-vault"
        }
      }
    }

Transfer vault to user

Authenticates the external vault and transfers it to the new owner.

PATCH /v2/vaults/{vault_urn}/transfers

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • The vault identifier. This parameter uses a specific notation: <creator uid>:<vault_name>.

Sensitive payload to be secured.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/v2/vaults/<vault-urn>/transfers' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "vault_address": "<vault-address>",
          "access_token": "<token>"
      }'
    

Response

Status Code

  • Success.

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Conflict.

  • Internal Server Error.

Example responses
  • {
      "value": {
        "metadata": {
          "created_at": "2022-02-24T21:36:45.677Z",
          "created_by": "user4",
          "description": "create hashicorp vault for transferring vault ownership tests synchronously",
          "invalid_auth": true,
          "invalid_owner": false,
          "owned_by": "user7",
          "owner_uid": 1000331007,
          "provider_name": "Hashicorp",
          "secret_preview": "vault-hashi-uc-trans-vault-secret-1vault-hashi-uc-trans-vault-secret-2vault-hashi-uc-trans-vault-secret-3",
          "total_secrets": 3,
          "updated_at": "2022-02-24T21:36:45.677Z",
          "vault_name": "vault-hashi-uc-trans-vault",
          "vault_type": "hashicorp_token",
          "vault_urn": "1000331031:vault-hashi-uc-trans-vault"
        }
      }
    }

Store secret or reference

Stores and secures a secret or secret reference to an external vault in an internal vault.

POST /v2/secrets

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Query Parameters

  • Validate secret reference.

    Default: false

  • Validate secret reference and save.

    Default: false

Sensitive payload to be secured.

Examples:
/v2/secrets
  • curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/secrets' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "secret_name": "generic-secret",
          "description": "This is my generic secret",
          "secret": {
            "generic": {
              "my_secret" : "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ"
            }
          },
          "type": "generic",
          "vault_urn": "0000000000:internal"
      }'
    

Response

Status Code

  • Success.

  • Created.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Conflict.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get a list of all secrets

Gets a list of all secrets that are stored in a Cloud Pak for Data instance.

GET /v2/secrets

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Query Parameters

  • The number of secrets to skip before starting to collect the result set.

    Default: 0

  • The number of secrets to return.

    Default: 50

  • Includes preview of secrets.

    Default: false

  • Sort by the field (for example: sort=secret_name or sort=-secret_name for descending order).\n The supported sort columns include: secret_name, type, description, created_by, vault_name, updated_at.

  • The type of secret. Vault support per type: generic (Internal, HashiCorp), certificate (Internal, CyberArk, HashiCorp), credentials (Internal, CyberArk, HashiCorp), key(Internal, CyberArk, HashiCorp), token (Internal, HashiCorp)

  • Secret name.

  • Match on all or any criteria, possible values.

    Allowable values: [any,all]

    Default: any

  • If true, returns all secrets when user has manage vaults and secrets permission.

    Default: false

  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Unauthorized.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Retrieve the details for a secret

Retrieves the details of a secret specified by a uniform resource name.

GET /v2/secrets/{secret_urn}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • Unique value identifying the secret for the user.

Query Parameters

  • The exclude_secret_data parameter can be applied in the query to remove the data section.

  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets/<secret_urn>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Non-Authoritative Information.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Update or refresh stored secret

Updates a secret or secret reference to an external vault. Note: You can update the secret itself and its description, but you cannot update the secret_name, vault_name, or type. These fields are immutable and cannot be edited.

PATCH /v2/secrets/{secret_urn}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • Unique value identifying the secret for the user.

Query Parameters

  • Validate secret reference.

    Default: false

  • Validate secret reference and save.

    Default: false

Sensitive payload to be secured.

Examples:
/v2/secrets/{secret_urn}
  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets/<secret_urn>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
        "description": "<description>",
        "secret": <secret>
      }'
    

Response

Status Code

  • Success.

  • Non-Authoritative Information.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Delete a secret from vault

Deletes an existing secret or secret reference to an external vault.

DELETE /v2/secrets/{secret_urn}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • Unique value identifying the secret for the user.

  • curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v2/secrets/1000330999:oracle-db-login-credentials' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Share a secret

Shares a secret or a secret reference to an external vault to other users and groups.

POST /v2/secrets/{secret_urn}/members

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • Unique value identifying the secret for the user.

List of users or groups.

  • curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/secrets/<secret_urn>/members' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "users": [
            {
              "username": <username>,
              "uid": <uid>
            }
          ],
          "groups": [
            {
              "group_name": <group-name>,
              "group_id": <group-id>
            }
          ]
        }'
    

Response

Status Code

  • Accepted.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Conflict.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get secret members

Retrieves a list of all the shared members for a secret or a secret reference to an external vault.

GET /v2/secrets/{secret_urn}/members

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • Unique value identifying the secret for the user.

Query Parameters

  • The number of secret members to skip before starting to collect the result set.

    Default: 0

  • The number of secrets to return.

    Default: 20

  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets/<secret_urn>/members' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Share or unshare a secret

Adds or removes users' or groups' access to secret or a secret reference to an external vault.

PUT /v2/secrets/{secret_urn}/members

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • Unique value identifying the secret for the user.

List of users or/and groups.

  • curl -k -X PUT 'https://{cpd_cluster_host}/zen-data/v2/secrets/<secret_urn>/members' -H 'Authorization: ZenApiKey {TOKEN}' -H 'Content-Type: application/json' -d '{
          "add_members": {
            "users": [
              {
                "uid": "1000331027",
                "username": "user22"
              }
            ],
            "groups": [
              {
                "group_name": "access_service_group",
                "group_id": "10003"
              }
            ]
          },
          "remove_members": {
            "users": [
              {
                "username": "user2",
                "uid": "1000331002"
              }
            ],
            "groups": [
              {
                "group_name": "provision_group",
                "group_id": "10002"
              }
            ]
          }
        }'
    

Response

Status Code

  • Accepted.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

No Sample Response

This method does not specify any sample responses.

Unshare secret

Removes users' or groups' access to secret or a secret reference to an external vault.

DELETE /v2/secrets/{secret_urn}/members

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Path Parameters

  • Unique value identifying the secret for the user.

List of users or/and groups.

  • curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v2/secrets/1000330999:oracle-db-login-credentials/members' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "users": [
            {
              "username": "user2",
              "uid": "1000331002"
            }
          ],
          "groups": [
            {
              "group_name": "provision_group",
              "group_id": "10002"
            }
          ]
        }'
    

Response

Status Code

  • Accepted.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Retrieve all my secrets

Returns a list of secrets that you stored in the internal vault. Note: The list does not contain any sensitive information. It contains identifiers of the secrets and metadata only.

GET /v2/secrets/bulk

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

Query Parameters

  • Comma-separated secret_urns.

  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets/bulk?secret_urns=secret-urn-1,secret-urn-2,secret-urn-3' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Retrieve a secret

Returns a secret that you stored in the internal vault for a specified reference. This method returns the entire secret payload in the same manner that it was stored in the vault.

POST /v2/serviceInstance/token

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Query Parameters

  • If this is set to true, then cookie with that instance ID is generated.

  • curl -k -X POST 'https://{cpd_cluster_host}/v2/serviceInstance/token' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
      "serviceInstanceID": {serviceInstanceID}
    }'
    

Response

Status Code

  • Success.

  • Error.

  • Unauthorized.

  • Not Found.

  • Conflict.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Create a volume

Creates a volume instance. Creates a volume instance that can be used to host data files, manage access to Cloud Pak for Data users, and be consumed by other services. You must include the volume instance definition as a JSON string in the HTTP request body. Can be initiated only by a user with the Create service instances permission.

POST /v1/volumes

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • Unique ID that is used to identify each transaction.

VolumeInstance metadata artifact that needs to be added to the database.

  • curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v1/volumes' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{
          "addon_type": "volumes",
          "addon_version": "-",
          "create_arguments": {
              "metadata": {
                "file_server": {
                  "start": true,
                }
                "volume_type": "EXISTING_PVC",
                "existing_pvc_name": "user-home-pvc"
              }
          },
          "namespace": "zen",
          "display_name": "existing-pv-sample-1"
        }'
    

Response

Status Code

  • Success.

  • Accepted.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Conflict.

  • Precondition Failed.

  • Internal Server Error.

  • Gateway Timeout.

No Sample Response

This method does not specify any sample responses.

Get a list of volume instances

Retrieves the list of volumes that you have access to.

GET /v1/volumes

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Query Parameters

  • If set to true returns all volume instances. This parameter can be used by an Administrator only.

  • ID of the volume.

  • Query by volume name.

  • Query by namespace.

  • The number of volumes to skip before starting to collect the result set.

    Default: 0

  • The number of volumes to return.

    Default: 20

  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/volumes' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    
  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/volumes?display_name=<insert-volume-name>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    
  • curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/volumes?fetch_all_instances=true' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get a list of persistent volume claims by namespace cluster

Retrieves a list of persistent volume claims based on a specified namespace. available in this ICP4Data cluster.

GET /v2/persistentvolumeclaims/{namespace}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • Namespace to get the claims from.

  • curl -k -X GET 'https://{cpd_cluster_host}/v2/persistentvolumeclaims/<namespace>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Update a volume

Updates a volume description. If it is an external SMB volume, this API can be also used to update the volume SMB/CIFS credentials.

PATCH /v1/volumes/{display_name}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • Name of the volume instance.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/v1/volumes/{display_name}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'  -d '{
          "description":"<new-description>",
          "cifs_username":"<new-cifs-username>",
          "cifs_password":"<new-cifs-password>"
          "supplemental_groups": [<group-id>, <group-id2>, ...]
          }'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get all namespaces

Retrieves all the namespaces available in this Cloud Pak for Data deployment.

GET /v2/namespaces

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Response

Status Code

  • Success.

  • Unauthorized.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Give access to a volume

Gives one or more users access to a volume instance. By default, only the user who created the volume instance is an administrator. You must include the volume instance ID as a JSON string in the HTTP request body. You can get the volume instance ID by using /zen-data/v3/service_instances.

POST /v2/serviceInstance/users

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Form Parameters

  • curl -k -X POST 'https://{cpd_cluster_host}/v2/serviceInstance/users' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: ZenApiKey {TOKEN}' -d '{
        "serviceInstanceID":"<volume-instance-ID>",
        "users":[
            {
              "display_name":"<display-name-of-user>",
              "role":"<access-level>",
              "uid":"<uid-of-user>",
              "username":"<username-of-user>"
            }
        ]
      }'
    

Response

Status Code

  • Success.

  • Error.

  • Unauthorized.

  • Not Found.

  • Resource Already Exists.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Revoke access to a volume

Revokes a user's access to the specified volume instance. You must include the volume instance ID as a JSON string in the HTTP request body. You can get the volume instance ID by using /zen-data/v3/service_instances.

DELETE /v2/serviceInstance/users

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Arrays of UID to delete.

  • curl -k -X DELETE 'https://{cpd_cluster_host}/v2/serviceInstance/users' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    -d '{
          "serviceInstanceID":"<volume-instance-ID>",
          "users":[
              "<uid-of-user>"
          ]
        }'
    

Response

Status Code

  • Success.

  • Error.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get a list of users with access to a volume

Retrieves the list of users who have access to the specified volume. The role of each user is also returned.

GET /v2/serviceInstance/users

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Query Parameters

  • Service Instance ID of the service.

  • Include profile picture or not.

    Default: false

  • Roles to query.

  • Includes group users or not.

    Default: false

  • curl -k -X GET 'https://{cpd_cluster_host}/v2/serviceInstance/users?sID=<volume_instance_id>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Error.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Change a user's role on a volume

Changes the user's role (access level) on the specified volume. You must include the volume instance ID as a JSON string in the HTTP request body. You can get the volume instance ID by using /zen-data/v3/service_instances. Note: Can be used only by the administrator of the service instance

PATCH /v2/serviceInstance/users/role

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

ServiceInstance metadata artifact that must be added to the database.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/v2/serviceInstance/users/role' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'  -d '{
      "serviceInstanceID":"<volume-instance-ID>",
      "roles":[
          {
            "uid":"<uid-of-user>",
            "newRole":"<new-access-level>"
          }
      ]
    }'
    

Response

Status Code

  • Success.

  • Error.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Start a file server with a persistent volume

Starts a service that contains a file server that supports upload, delete, list, and get operations on files.

POST /v1/volumes/volume_services/{display_name}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • The display name of the volume instance. You can get the volume instance display name by using /zen-data/v3/service_instances.

Volume metadata.

  • curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v1/volumes/volume_services/<display_name>' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{
    }'
    
  • curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v1/volumes/volume_services/<display_name>' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{
        "run_as_user": <uid-of-user>
      }
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Not Found.

  • Conflict.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Stop a file server on a volume

Stops the Volume File Server REST service on the specified volume instance. You can stop the file server to suspend unnecessary processing when the file server is not needed. Stopping the file server releases the compute resources that are used by the file server. Note: The data in the volume is not deleted.

DELETE /v1/volumes/volume_services/{display_name}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • Name of the persistent volume.

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

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Monitor a file server

Monitor a volume's file server status. If the file server in unavailable, you get a 502 Bad Gateway error.

GET /v1/monitor

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

    Examples:
    Authorization: ZenApiKey <token>
    Authorization: Bearer <token>
  • curl -k -X GET 'https://{cpd_cluster_host}/zen-volumes/<display_name>/v1/monitor' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

No Sample Response

This method does not specify any sample responses.

Upload file to the volume

Upload a file or create a directory (if no file provided to upload) into the volume. You must specify the target directory for the file on the volume and the path to the source file on the local file system.

PUT /v1/volumes/files/{file_path}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • Path leading upto where the file is uploaded in the volume. This must be url-encoded.

Query Parameters

  • The default value is false. Set the parameter to true to extract the contents of .zip, .tar, .tar.gz, or .tgz files to the specified directory. You can also upload binary-like files, that is, files that do not have a file extension.

    Default: false

  • Set themake_executable parameter to true to ensure that the file that you uploaded has executable permissions. This operation sets the +x bit across owner, group, and other (world) attributes of the directory. The make_executable parameter operates only on singleton files and has no effect on archived file uploads. When you uploaded an archive, the extracted files inherit the permissions from the source from where they were archived.

    Default: false

  • Set to true if and only if the name in file_path is not to be validated or sanitized.

    Default: false

  • The keep_root_dir parameter takes effect when uploading .zip file and extract is set to true. If keep_root_dir is set to true, then the extracted file structure will be the exactly same as the original file (root directories will be kept). If the flag is not set or set to false, then the extracted contents will be the same as the old behavior (root directories are removed).

    Default: false

Form Parameters

  • File to be uploaded. If this field is absent then a directory with the file-path is created.

  • # Upload a file to a volume
    
    curl -k -X PUT https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path> -H 'Authorization: ZenApiKey {TOKEN}' -H 'Content-Type: multipart/form-data' -F upFile='@<fully-qualified-file-path>'
    
    # Upload and extract the contents of a TAR.GZ file to the specified directory
    
    curl -k -X PUT https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?extract=true -H 'Authorization: ZenApiKey {TOKEN}' -H 'Content-Type: multipart/form-data' -F upFile='@<fully-qualified-file-path>'
    
    # Upload a file to a specified directory and make it executable
    
    curl -k -X PUT 'https://{cpd_cluster_host}/zen-volumes/{display_name}/v1/volumes/files/{directory_path}?make_executable=true' -H 'Authorization: ZenApiKey {TOKEN}' -H 'Content-Type: multipart/form-data' -F upFile=''
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

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

Download a file from a volume

Downloads the specified file from the specified volume. You can download a file or an archived directory in the name of your choice. Pass the file name of your choice in the optional override_file_name parameter. You can use the dry_run parameter to check if the asset at the target_file_path exists and return some useful metadata in the response header about the asset. You can also download an entire directory as an archive. Pass the archive type in as the value for the compress parameter in the request. If you issue this command from a web browser, the download prompt is displayed.

GET /v1/volumes/files/{file_path}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • Path leading upto where the file is uploaded in the volume. This must be url-encoded.

Query Parameters

  • Set to true to probe the file/directory without actually downloading it.

    Default: false

  • Pass a string here to override the name of the file downloaded.

  • Specify archive value to compress and download directory.

    Allowable values: [zip,tar,tar.gz]

  • # Download all files from a directory as a compressed archive
    
    curl -k -X GET 'https://{cpd_cluster_host}/zen-volumes/display_name/v1/volumes/files/target_file_path?compress=tar' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    
    # Download a file with dry_run=true
    
    curl -k -X GET https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?dry_run=true -H 'Authorization: ZenApiKey {TOKEN}'
    
    # Download a directory with dry_run=true
    
    curl -k -X GET https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?dry_run=true -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Partial Content.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Delete a directory or file on a volume

Deletes the specified file or directory on the specified volume.

DELETE /v1/volumes/files/{file_path}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • Path leading upto where the file is uploaded in the volume. This must be url-encoded.

  • curl -k -X DELETE 'https://{cpd_cluster_host}/zen-volumes/<display_name>/v1/volumes/files/<target_path>' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Copy, move, or rename a file or directory in a volume

Copies, moves, or renames files and directories within a volume.

PUT /v1/volumes/objects/copy

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Query Parameters

  • Set to false if you do not want to retain a copy of the object at the source_path (equivalent to a mv in UNIX). This value defaults to true, which keeps the object at the source_path.

    Default: true

  • Set to true if destination_path in the request body includes the name the object is to be copied as. This value defaults to false. That is, the object will be copied to the destination_path with the same name as in the source_path, creating any directories specified in the destination_path.

    Default: false

  • Set to true if you want to force replace a conflicting object at the destination_path. This value defaults to false. That is, if there are conflicts during the copy, move, or rename it is reported back to the user in the API response.

    Default: false

  • curl -k -X PUT 'https://{cpd_cluster_host}/zen-volumes/<volume_name>/v1/volumes/objects/copy' -H 'Authorization: ZenApiKey {TOKEN}' -H 'Content-Type: application/json' -d '{
        "source_path": "foo/bar",
        "destination_path": "baz"
        }
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get a list of the directories and files on a volume

Retrieves the list of all directories and files on the specified volume. You can use the recursive parameter to list contents from the <directory_path> recursively. The API supports a boolean query parameter tree. If set to true, the API returns the contents as a tree structure representing the actual directory structure. To use the tree option, you must set recursive to true. You can also optionally use the include_details query parameter to list the contents of the <directory_path> as an array of objects and their metadata.

GET /v1/volumes/directories/{directory_path}

Request

Custom Headers

  • Authorization: ZenApiKey | Bearer <token>

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

Path Parameters

  • The directory for which you want to display the contents. If you are referring to a nested directory, use URL encoding. For example, to create a reference to a directory called Shared files/analytics projects, enter: Shared%20files%2Fanalytics%20projects.

Query Parameters

  • The default value is false. Set the parameter to true to list the contents of the specified directory path recursively.

    Default: false

  • The default value is false. Set the parameter to true to have the API contents returned as a tree structure that represents the actual directory structure.

    Default: false

  • (To Be Deprecated Soon) Set to true if you want the response to indicate the type of entity (for example: file or directory)

    Default: false

  • If set to true, the API lists the contents from the directory_path as an array of objects with each object containing certain metadata information about the entity (file/directory) encountered at that location. The default is false. The information includes: content_length (in bytes), last_modified (in RFC 1123 format).

    Default: false

  • curl -k -X GET 'https://{cpd_cluster_host}/zen-volumes/<display_name>/v1/volumes/directories/<directory_path>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
    

Response

Status Code

  • Success.

  • Bad Request.

  • Unauthorized.

  • Forbidden.

  • Not Found.

  • Internal Server Error.

No Sample Response

This method does not specify any sample responses.