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 "https://{cpd_cluster_host}/icp4d-api/v1/authorize" \
-d "{\"username\":\"{username}\",\"password\":\"{password}\"}" \
-H "Content-Type: application/json"

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 "https://{cpd_cluster_host}/icp4d-api/v1/authorize" \
-d "{\"username\":\"{username}\",\"api_key\":\"{api_key}\"}" \
-H "Content-Type: application/json"

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

curl "https://{cpd_cluster_host}/v1/{method}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json"

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 "https://{cpd_cluster_host}/v1/{method}" \
-H "Authorization: ZenApiKey {token}" \
-H "Content-Type: application/json"

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 -X {request_method} "https://{cpd_cluster_host}/usermgmt/v1/{method}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json"

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} "{url}/v1/{method}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json"

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.

Before you get started, review What types of storage can you use to create a storage volume?

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

Change log

The Cloud Pak for Data Platform API describes the methods that are available in the current refresh of Cloud Pak for Data 5.0.x. The following methods and examples are new or changed:

  • A new service instance method to get the status of your instance
  • A new service instance method to patch only the version field in the custom resource of an instance
  • An updated service instance method to get the details of a specific instance

Related information

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

Request Body

Required*
loginCredentials
Examples: 
{
  "username": "admin",
  "password": "password"
}
{
  "username": "admin",
  "api_key": "<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

Response Body

loginResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • Accept-Language
    string

    Pass language for translated content.

    Example: en-US

Query Parameters

  • includeAll
    boolean

    Set to true to return all configurations.

    Default: false

    Example: true

  • 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

Response Body

Config

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

object
Examples: 
{
  "auto_signup": false,
  "externalLDAPEmailField": "mail",
  "externalLDAPFirstNameField": "givenName",
  "externalLDAPGroupField": "memberOf",
  "externalLDAPGroupMemberField": "member",
  "externalLDAPGroupSearchBase": "ou=groups,dc=ibm,dc=com",
  "externalLDAPGroupSearchField": "cn",
  "externalLDAPHost": "ldap://<host>",
  "externalLDAPLastNameField": "sn",
  "externalLDAPPort": 389,
  "externalLDAPSearchBase": "ou=people,dc=ibm,dc=com",
  "externalLDAPSearchField": "mail",
  "externalLDAPSearchPassword": "password",
  "externalLDAPSearchUser": "example@ibm.com",
  "externalLDAPPrefix": "uid=",
  "externalLDAPSuffix": "ou=People,dn=ibm,dn=com"
}
  • 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

Response Body

baseError

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Form Parameters

  • auto_signup
    Required*
    boolean

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

  • externalLDAPEmailField
    Required*
    string

    Email field in a user entry.

    Example: mail

  • externalLDAPFirstNameField
    Required*
    string

    First name field in a user entry.

    Example: givenName

  • externalLDAPGroupField
    Required*
    string

    Group field in a user entry.

    Example: memberOf

  • externalLDAPGroupMemberField
    Required*
    string

    Member field in a LDAP group entry.

    Example: member

  • externalLDAPGroupSearchBase
    Required*
    string

    Point in the LDAP tree where groups are searched from.

    Example: dc=wdp,dc=com

  • externalLDAPGroupSearchField
    Required*
    string

    LDAP field used for Group search criteria.

    Example: cn

  • externalLDAPHost
    Required*
    string

    The LDAP server's host.

    Example: ldap://<host>

  • externalLDAPLastNameField
    Required*
    string

    Last name field in a user entry.

    Example: sn

  • externalLDAPPort
    Required*
    number

    The LDAP server's port.

    Example: 389

  • externalLDAPPrefix
    Required*
    string

    The LDAP server's prefix.

  • externalLDAPSearchBase
    Required*
    string

    The LDAP server's search base.

    Example: dc=wdp,dc=com

  • externalLDAPSearchField
    Required*
    string

    The LDAP server's search field.

    Example: mail

  • externalLDAPSearchUser
    Required*
    string

    The LDAP server's search user.

    Example: search.user@wdp.com

  • password
    Required*
    string

    The password for login in clear text.

    Example: password

  • username
    Required*
    string

    The user name for login.

    Example: username

  • 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

Response Body

baseError

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 500

    Internal Server Error.

  • 503

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • includeAll
    boolean

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

    Example: true

  • search_str
    string

    Specify search string for pattern matching.

    Example: example

  • permissions
    string

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

    Example: manage_vaults_and_secrets,share_secrets

  • user_roles
    string

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

    Example: administrator_role,custom_user_role

  • roles
    string

    Comma-separated string. Return list of users with one of the roles assigned individually or through User-Groups.

    Example: api_admin,api_developer

  • negate_user_roles
    boolean

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

    Example: true

  • any_role
    boolean

    Flag to retrieve users having at least one role assigned.

    Example: true

  • no_roles
    boolean

    Flag to retrieve users having no roles assigned.

    Example: true

  • user_groups
    string

    Comma-separated string. Return list of group_ids.

    Example: 10000,10001

  • negate_user_groups
    boolean

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

    Example: true

  • include_users_count
    boolean

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

    Example: true

  • offset
    number

    Offset required for pagination.

  • limit
    number

    Max number of records to return in a page.

    Example: 25

  • sort_by
    string

    Sort user records based on a specific column.

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

    Example: created_timestamp

  • sort_order
    string

    Sorting order either ascending or descending.

    Allowable values: [ASC,DESC]

    Default: DESC

    Example: DESC

  • include_session_info
    boolean

    Set to true to return sessions of each user.

    Default: false

    Example: true

  • include_groups
    boolean

    Set to true to return groups for each user.

    Default: true

    Example: true

  • include_profile_picture
    boolean

    Set to true to return profile icon for each user.

    Default: false

    Example: true

  • 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_session_info={include_session_info}&include_groups={include_groups}&include_profile_picture={include_profile_picture}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'

Response

Response Body

User[]

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    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,
      "last_session_start_timestamp": 1704070800,
      "last_session_ended_timestamp": 1704114000,
      "sessionInfo": []
    }
  }
]
  • {
  "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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • uid
    Required*
    string

    Query for user profile by given user ID.

    Example: 1000331015

Query Parameters

  • include_session_info
    boolean

    Set to true to return sessions of the user.

    Default: false

    Example: true

  • curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/user/{uid}?include_session_info={include_session_info}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'

Response

Response Body

User

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 404

    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,
    "last_session_start_timestamp": 1704070800,
    "last_session_ended_timestamp": 1704114000,
    "sessionInfo": [
      {
        "session_id": "12ab3456-1234-5678-a39f-e8d9caf59ef7",
        "created_timestamp": 1704170800000,
        "can_refresh_until": 1704214000000,
        "misc": {
          "token": {
            "aud": "DSX",
            "iam": {
              "username": "example",
              "accessToken": "<access-token>"
            },
            "iss": "KNOXSSO",
            "sub": "example",
            "uid": 1000331015,
            "role": "Admin",
            "groups": [
              10000
            ],
            "username": "example",
            "csrf_token": "<csrf-token>",
            "session_id": "12ab3456-1234-5678-a39f-e8d9caf59ef7",
            "api_request": false,
            "permissions": [
              "manage_vaults_and_secrets",
              "share_secrets"
            ],
            "display_name": "example",
            "authenticator": "external",
            "can_refresh_until": 1704214000000
          },
          "access_token": "<token>",
          "remoteIP": "<remoteIP1>, <remoteIP2>"
        }
      }
    ]
  }
}
  • {
  "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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • migrated
    boolean

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

Request Body

User
Examples: 
{
  "displayName": "User",
  "email": "user@example.com",
  "username": "User",
  "password": "password"
}
{
  "displayName": "User",
  "email": "user@example.com",
  "username": "User",
  "password": "password",
  "misc": {
    "extAttributes": {
      "location": "Hawaii",
      "nationality": "United States",
      "userType": "Sr. Consultant"
    }
  }
}
{
  "displayName": "Admin",
  "email": "admin@example.com",
  "username": "Admin",
  "password": "password",
  "user_roles": [
    "zen_administrator_role"
  ]
}
{
  "username": "ldap.user@example.com",
  "displayName": "ldap.user@example.com",
  "email": "ldap.user@example.com",
  "authenticator": "external",
  "user_roles": [
    "zen_user_role"
  ],
  "misc": {
    "realm_name": "Microsoft_AD"
  }
}
  • 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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • uids
    string

    Comma-separated string of user IDs.

    Example: 1,2

  • count_only
    boolean

    Flag to send numbers of users in response.

    Example: true

  • 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

Response Body

User[]

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

Required*
User[]

List of user objects.

Examples: 
[
  {
    "displayName": "User",
    "email": "user@example.com",
    "username": "User",
    "password": "password"
  },
  {
    "displayName": "extAttributes User",
    "email": "user.extattr@example.com",
    "username": "User2",
    "password": "password",
    "misc": {
      "extAttributes": {
        "location": "Hawaii",
        "nationality": "United States",
        "userType": "Sr. Consultant"
      }
    }
  },
  {
    "displayName": "Admin",
    "email": "admin@example.com",
    "username": "Admin",
    "password": "password",
    "user_roles": [
      "zen_administrator_role"
    ]
  },
  {
    "username": "LDAP User",
    "displayName": "ldap.user@example.com",
    "email": "ldap.user@example.com",
    "authenticator": "external",
    "user_roles": [
      "zen_user_role"
    ],
    "misc": {
      "realm_name": "Microsoft_AD"
    }
  }
]
  • 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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

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

Response

Response Body

User

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 404

    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,
    "last_session_start_timestamp": 1704070800,
    "last_session_ended_timestamp": 1704114000,
    "sessionInfo": [
      {
        "session_id": "12ab3456-1234-5678-a39f-e8d9caf59ef7",
        "created_timestamp": 1704170800000,
        "can_refresh_until": 1704214000000,
        "misc": {
          "token": {
            "aud": "DSX",
            "iam": {
              "username": "example",
              "accessToken": "<access-token>"
            },
            "iss": "KNOXSSO",
            "sub": "example",
            "uid": 1000331015,
            "role": "Admin",
            "groups": [
              10000
            ],
            "username": "example",
            "csrf_token": "<csrf-token>",
            "session_id": "12ab3456-1234-5678-a39f-e8d9caf59ef7",
            "api_request": false,
            "permissions": [
              "manage_vaults_and_secrets",
              "share_secrets"
            ],
            "display_name": "example",
            "authenticator": "external",
            "can_refresh_until": 1704214000000
          },
          "access_token": "<token>",
          "remoteIP": "<remoteIP1>, <remoteIP2>"
        }
      }
    ]
  }
}

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
    string

    Authorization: ZenApiKey | Bearer <token>

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

Response

Response Body

object

Status Code

  • 200

    Success.

  • 401

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • username
    Required*
    string

    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

Response Body

User

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    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,
    "last_session_start_timestamp": 1704070800,
    "last_session_ended_timestamp": 1704114000,
    "sessionInfo": [
      {
        "session_id": "12ab3456-1234-5678-a39f-e8d9caf59ef7",
        "created_timestamp": 1704170800000,
        "can_refresh_until": 1704214000000,
        "misc": {
          "token": {
            "aud": "DSX",
            "iam": {
              "username": "example",
              "accessToken": "<access-token>"
            },
            "iss": "KNOXSSO",
            "sub": "example",
            "uid": 1000331015,
            "role": "Admin",
            "groups": [
              10000
            ],
            "username": "example",
            "csrf_token": "<csrf-token>",
            "session_id": "12ab3456-1234-5678-a39f-e8d9caf59ef7",
            "api_request": false,
            "permissions": [
              "manage_vaults_and_secrets",
              "share_secrets"
            ],
            "display_name": "example",
            "authenticator": "external",
            "can_refresh_until": 1704214000000
          },
          "access_token": "<token>",
          "remoteIP": "<remoteIP1>, <remoteIP2>"
        }
      }
    ]
  }
}
  • {
  "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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • username
    Required*
    string

    Name of the user to update.

    Example: example

Query Parameters

  • add_roles
    boolean

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

    Default: false

    Example: true

Request Body

updateUserParamsBody

Updated user object.

Examples: 
{
  "displayName": "Updated User",
  "email": "updateduser@ibm.com",
  "user_roles": [
    "user_role"
  ]
}
  • 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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • username
    Required*
    string

    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

Response Body

object

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 404

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • expiry_time
    string

    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

Response Body

object

Successful renew token response body.

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    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
    string

    Authorization: ZenApiKey | Bearer <token>

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

Response

Response Body

object

Successful API key response body.

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Could not find the user associated with the token.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

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

Response

Response Body

object

Successful revoke API key response.

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Could not find the user associated with the token.

  • 500

    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

  • 302

    Found. Redirecting to <url>.

  • 401

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Form Parameters

  • password
    Required*
    string

    The new password.

    Example: newPassword

  • currentPassword
    Required*
    string

    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

  • 401

    Unauthorized.

  • 404

    Not Found.

  • default

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Form Parameters

  • username
    Required*
    string

    The user name.

    Example: username

  • password
    Required*
    string

    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

  • 401

    Unauthorized.

  • 404

    Not Found.

  • default

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • dark_mode
    boolean

    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

Response Body

object

Successful setOwnProfile response body.

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • group_identifiers
    string

    Comma-separated string of group identifiers.

    Example: 10000,10001

  • role_identifiers
    string

    Comma-separated string of role identifiers.

    Example: administrator,api_user

  • include_members
    boolean

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

    Default: false

  • 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

Response Body

GetUserGroup[]

List of user groups.

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    Internal Server Error.

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

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

createUserGroupBody
Examples: 
{
  "name": "example group",
  "description": "This is a user group description.",
  "account_id": 1000,
  "role_identifiers": [
    "a5d6d89c-4852-4840-b300-4420a3081187",
    "8dfaf4c4-fe9c-4efa-9aaa-f70570fa5f18"
  ]
}
  • 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

Response Body

object

Status Code

  • 201

    Created.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • group_id
    Required*
    number

    Unique ID indentifying the User-Group.

    Example: 10001

Request Body

patchUserGroupBody
Examples: 
{
  "name": "example group",
  "description": "This is a user group description.",
  "account_id": 1000,
  "add_role_identifiers": [
    "a5d6d89c-4852-4840-b300-4420a3081187",
    "8dfaf4c4-fe9c-4efa-9aaa-f70570fa5f18"
  ],
  "remove_role_identifiers": [
    "5e4963e1-742d-49d1-b90a-f89d13225b93"
  ]
}
  • 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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • group_id
    Required*
    number

    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

Response Body

object

Status Code

  • 200

    Created.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • group_id
    Required*
    number

    User-Group identifier

    Example: 10001

Query Parameters

  • include_user_details
    boolean

    True if user_details are required in response.

    Default: false

  • offset
    number

    Offset required for pagination.

  • limit
    number

    Max number of records to return in a page.

    Example: 25

  • sort_by
    string

    Sorting the user records based upon specific column.

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

    Default: uid

    Example: uid

  • sort_order
    string

    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

Response Body

object

Successful GET group members response body.

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • group_id
    Required*
    number

    User-Group identifier.

    Example: 10001

Request Body

Required*
MembershipRules

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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • group_id
    Required*
    number

    User-Group identifier.

    Example: 10001

  • uid
    Required*
    number

    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

Response Body

object

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • group_id
    Required*
    number

    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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • rule_id
    Required*
    number

    Rule identifier.

    Example: 123

Request Body

Required*
DynamicMembershipRules

Payload containing group membership rules.

Examples: 
{
  "realm_name": "usermgmt_default",
  "logical_operator": "and",
  "rules": [
    {
      "attribute": "organization",
      "operator": "equal",
      "value": "IBM"
    },
    {
      "attribute": "location",
      "operator": "equal",
      "value": "San Jose"
    }
  ]
}
  • 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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • rule_id
    Required*
    number

    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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

object
Examples: 
{
  "search_field": "all",
  "search_string": "search",
  "limit": 10
}
  • 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

Response Body

object[]

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

object
Examples: 
{
  "search_string": "search",
  "limit": 10
}
  • 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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • Accept-Language
    string

    Pass language for translated content.

    Example: en-US

Query Parameters

  • include_users_count
    boolean

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

    Default: false

  • include_platform_users_count
    boolean

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

    Default: false

  • include_user_groups_count
    boolean

    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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

Required*
object

Create role object.

Examples: 
{
  "role_name": "Example Role",
  "description": "This is an example role.",
  "permissions": [
    "view_platform_health"
  ]
}
  • 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

Response Body

object

Status Code

  • 201

    Created.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • id
    Required*
    string

    Extension name of the role that needs to be updated.

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

Request Body

Required*
object

Update role object.

Examples: 
{
  "role_name": "Updated Example Role",
  "description": "This is an updated example role.",
  "permissions": [
    "view_platform_health",
    "manage_service_instances"
  ]
}
  • 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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • Accept-Language
    string

    Pass language for translated content.

    Example: en-US

Path Parameters

  • id
    Required*
    string

    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

Response Body

object

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 404

    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
    string

    Authorization: ZenApiKey | Bearer <token>

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

Response

Response Body

object

Status Code

  • 200

    Success.

  • 401

    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"
}

Give access to an instance for one or more users

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

POST /zen-data/v2/serviceInstance/users

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Form Parameters

  • serviceInstanceID
    Required*
    string
  • users
  • groups
  • curl -k -X POST 'https://{cpd_cluster_host}/zen-data/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

Response Body

SuccessPostResponse

Status Code

  • 200

    Success.

  • 400

    Error.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 409

    Resource Already Exists.

  • 500

    Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Revoke access to an instance

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

DELETE /zen-data/v2/serviceInstance/users

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

Required*
RevokeUsersSchema

Arrays of UID to delete.

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

Response

Response Body

SecretResponse

Status Code

  • 200

    Success.

  • 400

    Error.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get a list of users with access to an instance

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

GET /zen-data/v2/serviceInstance/users

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • sID
    Required*
    string

    Service Instance ID of the service.

  • include_profile_picture
    boolean

    Include profile picture or not.

    Default: false

  • role
    string

    Roles to query.

  • include_group_users
    boolean

    Includes group users or not.

    Default: false

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

Response

Response Body

SuccessGetResponse

Status Code

  • 200

    Success.

  • 400

    Error.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Change a user's role on an instance

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

PATCH /zen-data/v2/serviceInstance/users/role

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

PatchRole

ServiceInstance metadata artifact that must be added to the database.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Error.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    Internal Server Error.

No Sample Response

This method does not specify any sample responses.

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 /zen-data/v3/service_instances

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Request Body

Required*
ProvisionInstanceRequest

ServiceInstance metadata artifact that must be added to the database.

Examples: 
{
  "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}/zen-data/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}/zen-data/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}/zen-data/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}/zen-data/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}/zen-data/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}/zen-data/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

Response Body

InstanceResponse

Status Code

  • 200

    Success.

  • 202

    Accepted.

  • 400

    Bad Request.

  • 403

    Forbidden.

  • 409

    Conflict.

  • 412

    Precondition Failed.

  • 500

    Internal Server Error.

  • 504

    Gateway Timeout.

Example responses
  • {
  "id": 1585361220129
}

Get a service instance collection

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

This method no longer returns the total user count for the instance collection when the exclude_user_count query parameter is set to true.

The total user count is still returned as the default behavior for compatibility with an earlier version. However, use the new exclude_user_count parameter if you don’t require the total user count information. When you have many service instances, the response time is faster when you use the exclude_user_count parameter.

GET /zen-data/v3/service_instances

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Query Parameters

  • fetch_all_instances
    boolean

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

  • addon_type
    string

    Type of the add-on.

  • exclude_volumes
    boolean

    Exclude addon type volumes in the collection.

    Default: false

  • addon_version
    string

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

  • display_name
    string

    Name of the instance to query.

  • addon_category
    string

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

  • offset
    number

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

  • limit
    number

    The number of service instances to return.

    Example: 20

  • exclude_user_count
    boolean

    If set to true, computation of the total number of users that were added to a service instance will be skipped for all instances and omitted from the response.

    Default: false

  • # Retrieve service instances
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'

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

Response

Response Body

GetAllInstancesResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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. By default, this method returns the total user count in the return object in the "total_users": n response.

This method also returns a specific instance record with the service status if include_service_status is set to true.

This method fetches the status of the instance from the database only. It returns the live status if the status is not present in the status table, if the status expired (10 minutes), if the call failed, or if the status is unknown.

GET /zen-data/v3/service_instances/{instance_id}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

  • Accept-Language
    string

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

    Default: en

Path Parameters

  • instance_id
    Required*
    string

    service instance identifier

Query Parameters

  • include_service_status
    boolean

    If true service status is retrieved from the provider.

    Default: false

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

Response

Response Body

GetInstanceWithStatusResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    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 /zen-data/v3/service_instances/{instance_id}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • instance_id
    Required*
    string

    Service Instance Identifier

Query Parameters

  • force
    Required*
    boolean

    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}/zen-data/v3/service_instances/{instance_id}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'

Response

Response Body

InstanceResponse

Status Code

  • 200

    Success.

  • 202

    Accepted.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 409

    Conflict.

  • 412

    Precondition Failed.

  • 500

    Internal Server Error.

  • 504

    Gateway Timeout.

No Sample Response

This method does not specify any sample responses.

Get the status of service instances

Returns the status of service instances. Service instances are ordered by created_at date, most recent to oldest.

This method fetches the status of the instances from the database cache only.

By default, this method returns the status of service instances that the user has access to.

If the bulk parameter is set to true, this method retrieves the status of service instances for the specified list of service instances, which are provided by the instance_ids parameter.

GET /zen-data/v3/service_instances/statuses

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Query Parameters

  • bulk
    boolean

    If false, returns the status of service instances that the user has access to. If true, requires the instance_ids parameter to retrieve the status of the specified service instances.

    Default: false

  • instance_ids
    string

    To specify service IDs to retrieve the status for, set the bulk parameter to true and provide a comma-separated list of service instance IDs. You can provide a maximum of 20 service instance IDs.

  • include_count
    boolean

    Include the total count of instances that the user has access to. If not set to true, the total_count field is omitted from the response.

    Default: false

  • offset
    integer

    The number of service instances to skip, given the order of the service instances. Service instances are ordered by created_at date, most recent to oldest. If not specified, default is 0.

    Default: 0

  • limit
    integer

    The number of service instances to return.

    Default: 20

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

Response

Response Body

GetInstancesStatusBulkResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Upgrade a service instance

PUT /zen-data/v3/service_instances/upgrade

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • sID
    string

    ID of the service instance

  • service_status_check
    boolean

    If true, service status will be checked. The service status should be 'RUNNING' to perform upgrade.

    Default: false

  • force_version_upgrade
    boolean

    Set it to true, to patch only the version field in the custom resource (CR) during an upgrade, you can set the force_version_upgrade parameter to true and supply the targetVersion to set. If the force_version_upgrade parameter is set to true, the targetVersion parameter must be specified in the request body. If you specify args in the request body, they are ignored.

    Default: false

Request Body

UpgradeServiceInstanceArgs
  • curl -k -X PUT 'https://{cpd_cluster_host}/zen-data/v3/service_instances/upgrade' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'  -d '{
  "targetVersion":"2.0.0"
}'

Response

Response Body

successResponse

Status Code

  • 200

    Success.

  • 202

    Accepted.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    Internal Server Error.

Example responses
  • {
  "_messageCode_": "success",
  "message": "success",
  "requestObj": {},
  "status": "string"
}

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
    string

    Authorization: ZenApiKey | Bearer <token>

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

Response

Response Body

SuccessGetResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • retention_time
    integer

    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

Response Body

successResponseEvents

Status Code

  • 200

    Success.

  • 400

    Bad request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • retention_time
    integer

    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

Response Body

successResponseMetrics

Status Code

  • 200

    Success.

  • 400

    Bad request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

SMTPConfig

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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 406

    Conflict.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • monitor_type
    string

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

  • event_type
    string

    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

Response Body

SuccessGetResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • monitor_type
    Required*
    string

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

  • event_type
    Required*
    string

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

Request Body

EventConfig

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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 406

    Configuration Settings Invalid.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • alert_type
    Required*
    string

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

  • severity
    Required*
    string

    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
    string

    Event type.

Request Body

AlertRulesConfig

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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 406

    Configuration Settings Invalid.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    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

Response Body

SuccessGetResponse

Status Code

  • 200

    Success.

  • 204

    Config Not Found.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Form Parameters

  • host
    string

    The SNMP server host address.

  • community
    string

    The community string associated with the SNMP connection.

  • port
    string

    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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 406

    Configuration Settings Invalid.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    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

Response Body

SuccessGetResponse

Status Code

  • 200

    Success.

  • 204

    Configuration Not Found.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Form Parameters

  • webhook
    string

    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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 406

    Configuration Settings Invalid.

  • 500

    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 /zen-data/v1/extensions

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • Accept-Language
    string

    Pass language for translated content.

    Example: en-US

Query Parameters

  • extension_point_id
    string[]

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

  • id
    string

    Identifier of a particular extension.

  • extension_name
    string[]

    Array of particular extensions' names.

  • preference_type
    string

    Type of preference.

    Allowable values: [global,user]

    Default: user

  • source
    string

    Identifier for a particular source.

  • status
    string

    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

Response Body

SuccessGetResponseV2

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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 /zen-data/v1/custom_cards

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    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

Response Body

SuccessGetResponseV2

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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 /zen-data/v1/custom_cards/{key}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • key
    Required*
    string

    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.

Request Body

Required*
CustomCardReplaceObject

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

Response Body

object

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v1/custom_cards/{key}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • key
    Required*
    string

    The name of the card that you want to update.

Request Body

Required*
CustomCardUpdateObject

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

Response Body

SuccessPostResponseWithObjV2

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v1/custom_cards/{key}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • key
    Required*
    string

    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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/vaults

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Query Parameters

  • validate
    boolean

    Validate vault connection.

    Default: false

  • validate_and_save
    boolean

    Validate vault connection and save.

    Default: false

Request Body

Required*
NewVaultRequest

Sensitive payload to be secured.

Examples: 
{
  "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"
}
  • 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

Response Body

VaultResponse

Status Code

  • 200

    Success.

  • 201

    Test connection success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    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 /zen-data/v2/vaults

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Query Parameters

  • offset
    integer

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

    Default: 0

  • limit
    integer

    The number of vaults to return.

    Default: 50

  • include_secrets_preview
    boolean

    Preview secrets.

    Default: false

  • sort
    string

    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.

  • provider_name
    string

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

  • vault_name
    string

    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
    string

    Match on all or any criteria, possible values.

    Allowable values: [any,all]

    Default: any

  • include_vaults_for_management
    boolean

    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

Response Body

GetAllVaultsResponse

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/vaults/{vault_urn}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • vault_urn
    Required*
    string

    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

Response Body

VaultDetailsResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/vaults/{vault_urn}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • vault_urn
    Required*
    string

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

Query Parameters

  • validate
    boolean

    Validate vault connection.

    Default: false

  • validate_and_save
    boolean

    Validate vault connection and save.

    Default: false

Request Body

Required*
PatchVaultRequest

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

Response Body

VaultDetailsResponse

Status Code

  • 200

    Success.

  • 201

    Test connection success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/vaults/{vault_urn}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • vault_urn
    Required*
    string

    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

Response Body

VaultResponse

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/vaults/{vault_urn}/transfers

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • vault_urn
    Required*
    string

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

Query Parameters

  • force
    boolean

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

    Default: false

Request Body

Required*
TransferVaultRequest

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

Response Body

TransferVaultResponse

Status Code

  • 200

    Success.

  • 202

    Transfer vault request accepted.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    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 /zen-data/v2/vaults/{vault_urn}/transfers

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • vault_urn
    Required*
    string

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

Request Body

Required*
PatchTransferredVaultRequest

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

Response Body

TransferVaultResponse

Status Code

  • 200

    Success.

  • 202

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    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 /zen-data/v2/secrets

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Query Parameters

  • validate
    boolean

    Validate secret reference.

    Default: false

  • validate_and_save
    boolean

    Validate secret reference and save.

    Default: false

Request Body

Required*
NewSecretRequest

Sensitive payload to be secured.

Examples: 
{
  "secret_name": "generic-secret,",
  "description": "This is a generic secret.",
  "secret": {
    "generic": {
      "my_secret": "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ"
    }
  },
  "type": "generic,",
  "vault_urn": "0000000000:internal"
}
  • 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

Response Body

SecretResponse

Status Code

  • 200

    Success.

  • 201

    Created.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    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 /zen-data/v2/secrets

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Query Parameters

  • offset
    integer

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

    Default: 0

  • limit
    integer

    The number of secrets to return.

    Default: 50

  • include_secrets_preview
    boolean

    Includes preview of secrets.

    Default: false

  • sort
    string

    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.

  • type
    string

    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
    string

    Secret name.

  • match
    string

    Match on all or any criteria, possible values.

    Allowable values: [any,all]

    Default: any

  • include_secrets_for_management
    boolean

    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

Response Body

GetAllSecretsResponse

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 500

    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 /zen-data/v2/secrets/{secret_urn}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • secret_urn
    Required*
    string

    Unique value identifying the secret for the user.

Query Parameters

  • exclude_secret_data
    Required*
    boolean

    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

Response Body

SecretDetailsResponse

Status Code

  • 200

    Success.

  • 203

    Non-Authoritative Information.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/secrets/{secret_urn}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • secret_urn
    Required*
    string

    Unique value identifying the secret for the user.

Query Parameters

  • validate
    boolean

    Validate secret reference.

    Default: false

  • validate_and_save
    boolean

    Validate secret reference and save.

    Default: false

Request Body

Required*
PatchSecretRequest

Sensitive payload to be secured.

Examples: 
{
  "description": "<description>",
  "secret": "<secret>"
}
  • 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

Response Body

SecretDetailsResponse

Status Code

  • 200

    Success.

  • 203

    Non-Authoritative Information.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/secrets/{secret_urn}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • secret_urn
    Required*
    string

    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

Response Body

SecretResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/secrets/{secret_urn}/members

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • secret_urn
    Required*
    string

    Unique value identifying the secret for the user.

Request Body

Required*
SecretMembers

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

Response Body

SecretResponse

Status Code

  • 202

    Accepted.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    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 /zen-data/v2/secrets/{secret_urn}/members

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • secret_urn
    Required*
    string

    Unique value identifying the secret for the user.

Query Parameters

  • offset
    integer

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

    Default: 0

  • limit
    integer

    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

Response Body

GetSecretMembersResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/secrets/{secret_urn}/members

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • secret_urn
    Required*
    string

    Unique value identifying the secret for the user.

Request Body

Required*
UpdateSecretMembers

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

  • 202

    Accepted.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    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 /zen-data/v2/secrets/{secret_urn}/members

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Path Parameters

  • secret_urn
    Required*
    string

    Unique value identifying the secret for the user.

Request Body

Required*
SecretMembers

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

Response Body

SecretResponse

Status Code

  • 202

    Accepted.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/secrets/bulk

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Query Parameters

  • secret_urns
    Required*
    string

    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

Response Body

SecretDetailsResponse[]

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/serviceInstance/token

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • setCookie
    boolean

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

Request Body

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

Response

Response Body

SuccessTokenResponse

Status Code

  • 200

    Success.

  • 400

    Error.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    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 /zen-data/v1/volumes

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>
  • IBM-CPD-Transaction-ID
    string

    Unique ID that is used to identify each transaction.

Request Body

Required*
ProvisionInstanceRequest

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

Response Body

InstanceResponse

Status Code

  • 200

    Success.

  • 202

    Accepted.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 409

    Conflict.

  • 412

    Precondition Failed.

  • 500

    Internal Server Error.

  • 504

    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.

This method no longer returns the total user count for the volume instance collection when the exclude_user_count query parameter is set to true.

The total user count is still returned as the default behavior for compatibility with an earlier version. However, use the new exclude_user_count parameter if you don't require the total user count information. When you have many service instances, the response time is faster when you use the exclude_user_count parameter.

GET /zen-data/v1/volumes

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • fetch_all_instances
    boolean

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

  • id
    string

    ID of the volume.

  • display_name
    string

    Query by volume name.

  • namespace
    string

    Query by namespace.

  • offset
    integer

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

    Default: 0

  • limit
    integer

    The number of volumes to return.

    Default: 20

  • exclude_user_count
    boolean

    If set to true, computation of the total number of users that were added to a service instance will be skipped for all instances and omitted from the response.

    Default: false

  • 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

Response Body

GetAllInstancesResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/persistentvolumeclaims/{namespace}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • namespace
    Required*
    string

    Namespace to get the claims from.

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

Response

Response Body

SuccessGetResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 500

    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 /zen-data/v1/volumes/{display_name}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • display_name
    Required*
    string

    Name of the volume instance.

Request Body

object
  • 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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v2/namespaces

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

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

Response

Response Body

SuccessGetResponse

Status Code

  • 200

    Success.

  • 401

    Unauthorized.

  • 500

    Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Give access to an instance for one or more users

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

POST /zen-data/v2/serviceInstance/users

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Form Parameters

  • serviceInstanceID
    Required*
    string
  • users
  • groups
  • curl -k -X POST 'https://{cpd_cluster_host}/zen-data/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

Response Body

SuccessPostResponse

Status Code

  • 200

    Success.

  • 400

    Error.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 409

    Resource Already Exists.

  • 500

    Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Revoke access to an instance

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

DELETE /zen-data/v2/serviceInstance/users

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

Required*
RevokeUsersSchema

Arrays of UID to delete.

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

Response

Response Body

SecretResponse

Status Code

  • 200

    Success.

  • 400

    Error.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Get a list of users with access to an instance

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

GET /zen-data/v2/serviceInstance/users

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • sID
    Required*
    string

    Service Instance ID of the service.

  • include_profile_picture
    boolean

    Include profile picture or not.

    Default: false

  • role
    string

    Roles to query.

  • include_group_users
    boolean

    Includes group users or not.

    Default: false

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

Response

Response Body

SuccessGetResponse

Status Code

  • 200

    Success.

  • 400

    Error.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    Internal Server Error.

No Sample Response

This method does not specify any sample responses.

Change a user's role on an instance

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

PATCH /zen-data/v2/serviceInstance/users/role

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Request Body

PatchRole

ServiceInstance metadata artifact that must be added to the database.

  • curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Error.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-data/v1/volumes/volume_services/{display_name}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • display_name
    Required*
    string

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

Request Body

Required*
VolumeObject

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

Response Body

SuccessPostResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 409

    Conflict.

  • 500

    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 /zen-data/v1/volumes/volume_services/{display_name}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • display_name
    Required*
    string

    Name of the persistent volume.

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

Response

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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 /zen-volumes/v1/monitor

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    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

Response Body

SuccessGetResponse

Status Code

  • 200

    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 /zen-volumes/v1/volumes/files/{file_path}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • file_path
    Required*
    string

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

Query Parameters

  • extract
    boolean

    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

  • make_executable
    boolean

    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

  • ignore_name_validation
    boolean

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

    Default: false

  • keep_root_dir
    boolean

    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

  • upFile
    binary

    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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-volumes/v1/volumes/files/{file_path}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • file_path
    Required*
    string

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

Query Parameters

  • dry_run
    boolean

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

    Default: false

  • override_file_name
    string

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

  • compress
    string

    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

Response Body

binary

Status Code

  • 200

    Success.

  • 206

    Partial Content.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-volumes/v1/volumes/files/{file_path}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • file_path
    Required*
    string

    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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 404

    Not Found.

  • 500

    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 /zen-volumes/v1/volumes/objects/copy

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Query Parameters

  • keep_source
    boolean

    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

  • destination_in_path
    boolean

    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

  • overwrite_destination
    boolean

    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

Request Body

CopyEntityObject
  • 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

Response Body

successResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    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 /zen-volumes/v1/volumes/directories/{directory_path}

Request

Custom Headers

  • Authorization
    string

    Authorization: ZenApiKey | Bearer <token>

    Examples: 
    ZenApiKey <token>
    Bearer <token>

Path Parameters

  • directory_path
    Required*
    string

    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

  • recursive
    boolean

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

    Default: false

  • tree
    boolean

    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

  • include_type
    boolean

    (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

  • include_details
    boolean

    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

Response Body

SuccessGetDirectoryResponse

Status Code

  • 200

    Success.

  • 400

    Bad Request.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not Found.

  • 500

    Internal Server Error.

No Sample Response

This method does not specify any sample responses.

id=curlclassName=tab-item-selected