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
administratorormanage_userspermissions can also create, update, or delete user-profiles. - Configure monitors and alerts
-
A Cloud Pak for Data administrator can browse generated events and configure monitors and alerts.
- Manage secrets and vaults
-
Authenticated users can safeguard credentials and secrets with access control and audit logging.
- 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 persistent volume instances
-
Administrators with the
Create service instancespermission can create and manage persistent volume instances on your existing Cloud Pak® for Data storage devices.
Using Authorization: Bearer token
If Identity and Access Management (IAM) are not enabled, you can generate a token by using your username and password against the Get authorization token endpoint.
If IAM is enabled, you can generate a token by using your username and password against the /idprovider/v1/auth/identitytoken endpoint.
Using Authorization: ZenApiKey token
With a platform API key, you can access everything that you would typically be able to access when you log in to the Cloud Pak for Data web client.
Note: Watson™ Data APIs and Watson Machine Learning APIs do not support ZenApiKey authorization.
To generate a platform API key through the user experience:
- Log in to the web client.
- From the toolbar, click your avatar.
- Click Profile and settings.
- Click API key > Generate new key.
- Click Generate.
- Click Copy and save your key somewhere safe. You cannot recover this key if you lose it.
Alternatively, you 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.
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 absolutely necessary, and take steps to enable SSL as soon as possible.
To disable SSL verification for a curl request, use the --insecure (-k) option with the request.
Example that disables SSL verification
curl -k -X {request_method} "{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 completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user. Response codes are listed with the method.
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.
Managing secrets and vaults
You can safeguard credentials and secrets with access control and audit logging by using the Credentials 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 that requires reporting and auditing of privileged credential usage, and forensic analysis of access. Storing and accessing credentials in plain text on applications and services poses a serious security risk. You need tools that provide access and secrets management, both for system identities and user identities.
The Vaults and Secrets Management APIs introduce a centralized mechanism that is hardened by data encryption, secure access control, authorization checks, and auditing, which addresses credential management in Cloud Pak for Data across all services. 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 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.
Vaults and secrets management can also be done by using a user interface. For more information, see Managing secrets and vaults.
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 easy 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.
Template types:
- The
donuttemplate illustrates an array of values as percentages in a donut chart. - The
bartemplate creates a two-dimensional bar graph. - The
big_numbertemplate highlights significant data. - The
text_listdisplays a list of text strings. - The
number_listdisplays a list of numeric values and associated text. - The
listdisplays a list of navigation links. The list can contain headers and associated clickable links. - The
content_blockdisplays rows of text or links. Each row can be a paragraph of text or clickable links.
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.
Change log
The Cloud Pak for Data Platform 4.7.0 API now includes the following methods and examples:
- Alerting APIs
- Credentials and secrets APIs
- Home page custom cards APIs
- Volumes APIs
In the Cloud Pak for Data Platform 4.7.0 API, you can use two new methods in the Alerting APIs to delete monitoring events or metrics records that are older than a specified number of days.
- Delete monitoring events. You can use this method to delete events. By default, events are stored for three days.
- Delete metrics records. You can use this method to delete metrics records. By default, metrics are stored for 30 days.
Methods
Get configuration info
This API allows users to view configuration information for the usermgmt environment and LDAP.
GET /usermgmt/v1/usermgmt/config
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Pass language for translated content.
Example:
en-US
Query Parameters
Set to true to return all configurations.
Default:
falseExample:
true
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/config?includeAll={includeAll}' -H 'Accept-Language: en-US' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
Automatically approve users who request access, without explicit admin approval.
The customer's LDAP server to use for authentication.
If unset, then it means an external LDAP server is not used.
Indicates the LDAP mechanism to use.
Port number. (Default=389)
This is used to complete the full distinguished name (DN) to identify a user entry.
For example, a suffix could be something like "ou=People,dn=ibm,dn=com". Then if the username is "testuser", the full DN for that user would be "uid=testuser,ou=People,dn=ibm,dn=com".
Status Code
Success.
Bad Request.
Unauthorized.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
{
"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"
}Automatically approve users who request access, without explicit admin approval.
Email field in a user entry.
First name field in a user entry.
Group field in a user entry.
Member field in a LDAP group entry.
Point in the LDAP tree where groups are searched from.
LDAP field used for Group search criteria.
LDAP server to use for authentication.
If unset, it means an external LDAP server is not used.
Last name field in a user entry.
Port number (Default=389).
Point in the LDAP tree where users are searched from.
LDAP field used for search criteria.
Password of the Search User.
Functional user ID that is used to perform user lookups.
LDAP prefix for identifying a user entry.
LDAP suffix for identifying a user entry.
curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/config' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ auto_signup: {auto_signup}, externalLDAPEmailField: {externalLDAPEmailField}, externalLDAPFirstNameField: {externalLDAPFirstNameField}, externalLDAPGroupField: {externalLDAPGroupField}, externalLDAPGroupMemberField: {externalLDAPGroupMemberField}, externalLDAPGroupSearchBase: {externalLDAPGroupSearchBase}, externalLDAPGroupSearchField: {externalLDAPGroupSearchField}, externalLDAPHost: {externalLDAPHost}, externalLDAPLastNameField: {externalLDAPLastNameField}, externalLDAPPort: {externalLDAPPort}, externalLDAPSearchBase: {externalLDAPSearchBase}, externalLDAPSearchField: {externalLDAPSearchField}, externalLDAPSearchPassword: {externalLDAPSearchPassword}, externalLDAPSearchUser: {externalLDAPSearchUser}, externalLDAPPrefix: {externalLDAPPrefix}, externalLDAPSuffix: {externalLDAPSuffix} }'
Response
The identifier of the response.
The explanation of the
_messageCode_.
Status Code
Success.
Bad Request.
Unauthorized.
{ "_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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Form Parameters
Automatically approve users who request access, without explicit admin approval.
Email field in a user entry.
Example:
mailFirst name field in a user entry.
Example:
givenNameGroup field in a user entry.
Example:
memberOfMember field in a LDAP group entry.
Example:
memberPoint in the LDAP tree where groups are searched from.
Example:
dc=wdp,dc=comLDAP field used for Group search criteria.
Example:
cnThe LDAP server's host.
Example:
ldap://<host>Last name field in a user entry.
Example:
snThe LDAP server's port.
Example:
389The LDAP server's prefix.
The LDAP server's search base.
Example:
dc=wdp,dc=comThe LDAP server's search field.
Example:
mailThe LDAP server's search user.
Example:
search.user@wdp.comThe password for login in clear text.
Example:
passwordThe user name for login.
Example:
username
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/preauth/validateConfig' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer {token}' --data-urlencode 'externalLDAPHost{externalLDAPHost}=' --data-urlencode 'externalLDAPPort{externalLDAPPort}=' --data-urlencode 'username{username}=' --data-urlencode 'password{password}=' --data-urlencode 'externalLDAPMechanism{externalLDAPMechanism}=' --data-urlencode 'externalLDAPPrefix={externalLDAPPrefix}' --data-urlencode 'externalLDAPSuffix={externalLDAPSuffix}' --data-urlencode 'externalLDAPSearchUser={externalLDAPSearchUser}' --data-urlencode 'externalLDAPSearchPassword{externalLDAPSearchPassword}=' --data-urlencode 'externalLDAPSearchBase={externalLDAPSearchBase}' --data-urlencode 'externalLDAPSearchField{externalLDAPSearchField}=' --data-urlencode 'externalLDAPGroupField{externalLDAPGroupField}='
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
{
"username": "admin",
"password": "password"
}{
"username": "admin",
"api_key": "<api_key>"
}IBM Cloud Pak for Data username.
IBM Cloud Pak for Data password.
IBM Cloud Pak for Data 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
The identifier of the response.
The explanation of the
_messageCode_.The bearer token associated with a username.
Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Status Code
Success.
Bad Request.
Unauthorized.
Internal Server Error.
{ "_messageCode_": "200", "message": "Success", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" }{ "_statusCode_": 400, "exception": "Please provide one of api_key/password to receive the token.", "message": "Bad Request" }{ "_statusCode_": 401, "exception": "User unauthorized to invoke this endpoint.", "message": "Unauthorized" }{ "_statusCode_": 500, "message": "Internal server error" }
Get users
This API allows users to view and filter a list of user details on the platform.
Details include user info, groups, roles, and permissions related to the user.
GET /usermgmt/v1/usermgmt/users
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Set to true to return all users including users in pending/denied access states.
Example:
trueSpecify search string for pattern matching.
Example:
exampleComma-separated string. Return list of users with one of the permissions.
Example:
manage_vaults_and_secrets,share_secretsComma-separated string. Return list of users with one of the roles.
Example:
administrator_role,custom_user_roleComma-separated string. Return list of users with one of the roles assigned individually or through User-Groups.
Example:
api_admin,api_developerFlag to retrieve users that do not belong to mentioned user_roles.
Example:
trueFlag to retrieve users having at least one role assigned.
Example:
trueFlag to retrieve users having no roles assigned.
Example:
trueComma-separated string. Return list of group_ids.
Example:
10000,10001Flag to retrieve users that do not belong to mentioned user_groups.
Example:
trueFlag to retrieve count of all Cloud Pak for Data users.
Example:
trueOffset required for pagination.
Max number of records to return in a page.
Example:
25Sort user records based on a specific column.
Allowable values: [
uid,username,displayName,email,created_timestamp]Example:
created_timestampSorting order either ascending or descending.
Allowable values: [
ASC,DESC]Default:
DESCExample:
DESCSet to true to return groups for each user.
Default:
trueExample:
trueSet to true to return profile icon for each user.
Default:
falseExample:
true
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/users?includeAll={includeAll}&search_str={search_str}&permissions={permissions}&user_roles={user_roles}&roles={roles}&negate_user_roles={negate_user_roles}&any_role={any_role}&no_roles={no_roles}&user_groups={user_groups}&negate_user_groups={negate_user_groups}&include_users_count={include_users_count}&offset={offset}&limit={limit}&sort_by={sort_by}&sort_order={sort_order}&include_groups={include_groups}&include_profile_picture={include_profile_picture}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
The user name.
Example:
exampleThe authenticator for the user.
Possible values: [
default,external]Example:
externalThe date and time that the user account was created.
Example:
1655162210393The current status of the user's account.
Possible values: [
locked,enabled,disabled]Example:
enabledIndicate whether user is deletable.
Example:
trueThe name that is displayed for this user.
Example:
exampleThe user's unique email address.
Example:
example@ibm.com- Examples:
[ "administrator", "can_provision" ] Group that is returned with a user object's "groups" field.
Internal users will not show up in the get all users request.
Milliseconds from epoch. Tracks when this record was last updated.
Example:
1655162210393- Examples:
[ "manage_vaults_and_secrets", "share_secrets" ] Base64 encoded image.
Example:
iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=The role assigned to the user.
Possible values: [
Admin,User]Example:
AdminThe unique identifier for the user.
Example:
1000331015The roles assigned to the user.
Examples:[ "administrator_role" ]Collection of trivial miscellaneous user attributes.
Examples:{ "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true }
Status Code
Success.
Bad Request.
Unauthorized.
[ { "authenticator": "external", "created_timestamp": 1655162210393, "current_account_status": "enabled", "deletable": true, "displayName": "example", "email": "example@ibm.com", "group_roles": [ "administrator", "can_provision" ], "groups": [ { "group_id": 10000, "name": "All users", "description": "All users are implicitly part of this group.", "added_separately": true, "created_at": "2022-05-25T22:03:31.193Z", "created_by": "admin", "updated_at": "2022-05-25T22:03:31.193Z", "members_count": 42, "misc": { "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true } } ], "internal_user": false, "last_modified_timestamp": 1655162210393, "permissions": [ "manage_vaults_and_secrets", "share_secrets" ], "profile_picture": "iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=", "role": "Admin", "uid": 1000331015, "user_roles": [ "administrator_role" ], "username": "example", "misc": { "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true } } ]{ "exception": "Request validation failed: Parameter (includeAll) is not a valid boolean: notABool", "_messageCode_": "bad_request", "message": "Payload is invalid", "_statusCode_": 400 }
Get user by ID
This API allows users to view details about one user via their user ID.
GET /usermgmt/v1/usermgmt/user/{uid}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Query for user profile by given user ID.
Example:
1000331015
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/user/{uid}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
The user name.
Example:
exampleThe authenticator for the user.
Possible values: [
default,external]Example:
externalThe date and time that the user account was created.
Example:
1655162210393The current status of the user's account.
Possible values: [
locked,enabled,disabled]Example:
enabledIndicate whether user is deletable.
Example:
trueThe name that is displayed for this user.
Example:
exampleThe user's unique email address.
Example:
example@ibm.com- Examples:
[ "administrator", "can_provision" ] Group that is returned with a user object's "groups" field.
Internal users will not show up in the get all users request.
Milliseconds from epoch. Tracks when this record was last updated.
Example:
1655162210393- Examples:
[ "manage_vaults_and_secrets", "share_secrets" ] Base64 encoded image.
Example:
iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=The role assigned to the user.
Possible values: [
Admin,User]Example:
AdminThe unique identifier for the user.
Example:
1000331015The roles assigned to the user.
Examples:[ "administrator_role" ]Collection of trivial miscellaneous user attributes.
Examples:{ "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true }
Status Code
Success.
Bad Request.
Not Found.
{ "authenticator": "external", "created_timestamp": 1655162210393, "current_account_status": "enabled", "deletable": true, "displayName": "example", "email": "example@ibm.com", "group_roles": [ "administrator", "can_provision" ], "groups": [ { "group_id": 10000, "name": "All users", "description": "All users are implicitly part of this group.", "added_separately": true, "created_at": "2022-05-25T22:03:31.193Z", "created_by": "admin", "updated_at": "2022-05-25T22:03:31.193Z", "members_count": 42, "misc": { "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true } } ], "internal_user": false, "last_modified_timestamp": 1655162210393, "permissions": [ "manage_vaults_and_secrets", "share_secrets" ], "profile_picture": "iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=", "role": "Admin", "uid": 1000331015, "user_roles": [ "administrator_role" ], "username": "example", "misc": { "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true } }{ "exception": "UID is invalid", "_messageCode_": "bad_request", "message": "Payload is invalid", "_statusCode_": 400 }{ "exception": "user details not found", "_messageCode_": "not_found", "message": "The asset is not found", "_statusCode_": 404 }
Grant access to user
This API allows users with an administrator role to grant Cloud Pak for Data platform access to a user.
The password field should not be included when creating a user authenticated via an external identity provider such as LDAP/SAML/IAM. It is highly encouraged to authenticate users via an external identity provider.
The email field must be unique. An error code 400 will be returned if the email address is already in use.
POST /usermgmt/v1/user
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Set to true when this endpoint is used for migration purposes.
{
"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"
}
}The user name.
Example:
exampleThe authenticator for the user.
Allowable values: [
default,external]Example:
externalThe date and time that the user account was created.
Example:
1655162210393The current status of the user's account.
Allowable values: [
locked,enabled,disabled]Example:
enabledIndicate whether user is deletable.
Example:
trueThe name that is displayed for this user.
Example:
exampleThe user's unique email address.
Example:
example@ibm.com- Examples:
[ "administrator", "can_provision" ] Group that is returned with a user object's "groups" field.
Internal users will not show up in the get all users request.
Milliseconds from epoch. Tracks when this record was last updated.
Example:
1655162210393- Examples:
[ "manage_vaults_and_secrets", "share_secrets" ] Base64 encoded image.
Example:
iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=The role assigned to the user.
Allowable values: [
Admin,User]Example:
AdminThe unique identifier for the user.
Example:
1000331015The roles assigned to the user.
Examples:[ "administrator_role" ]Collection of trivial miscellaneous user attributes.
Examples:{ "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true }
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{ "displayName":{displayName}, "email":{email}, "username":{username}, "password":{password}, "user_roles":{user_roles} }'curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{ "username":{username}, "displayName":{displayName}, "email":{email}, "authenticator":{authenticator}, "user_roles":{user_roles}, "misc": { "realm_name":{realm_name}, "extAttributes":{extAttributes} } }'
Response
The identifier of the response.
The explanation of the
_messageCode_.
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Comma-separated string of user IDs.
Example:
1,2Flag to send numbers of users in response.
Example:
true
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/users?uids={uids}&count_only={count_only}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
The user name.
Example:
exampleThe authenticator for the user.
Possible values: [
default,external]Example:
externalThe date and time that the user account was created.
Example:
1655162210393The current status of the user's account.
Possible values: [
locked,enabled,disabled]Example:
enabledIndicate whether user is deletable.
Example:
trueThe name that is displayed for this user.
Example:
exampleThe user's unique email address.
Example:
example@ibm.com- Examples:
[ "administrator", "can_provision" ] Group that is returned with a user object's "groups" field.
Internal users will not show up in the get all users request.
Milliseconds from epoch. Tracks when this record was last updated.
Example:
1655162210393- Examples:
[ "manage_vaults_and_secrets", "share_secrets" ] Base64 encoded image.
Example:
iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=The role assigned to the user.
Possible values: [
Admin,User]Example:
AdminThe unique identifier for the user.
Example:
1000331015The roles assigned to the user.
Examples:[ "administrator_role" ]Collection of trivial miscellaneous user attributes.
Examples:{ "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true }
Status Code
Success.
Bad Request.
Unauthorized.
{ "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. An error code 400 will be returned if the email address is already in use.
POST /usermgmt/v1/user/bulk
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
List of user objects.
[
{
"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"
}
}
]The user name.
Example:
exampleThe authenticator for the user.
Allowable values: [
default,external]Example:
externalThe date and time that the user account was created.
Example:
1655162210393The current status of the user's account.
Allowable values: [
locked,enabled,disabled]Example:
enabledIndicate whether user is deletable.
Example:
trueThe name that is displayed for this user.
Example:
exampleThe user's unique email address.
Example:
example@ibm.com- Examples:
[ "administrator", "can_provision" ] Group that is returned with a user object's "groups" field.
Internal users will not show up in the get all users request.
Milliseconds from epoch. Tracks when this record was last updated.
Example:
1655162210393- Examples:
[ "manage_vaults_and_secrets", "share_secrets" ] Base64 encoded image.
Example:
iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=The role assigned to the user.
Allowable values: [
Admin,User]Example:
AdminThe unique identifier for the user.
Example:
1000331015The roles assigned to the user.
Examples:[ "administrator_role" ]Collection of trivial miscellaneous user attributes.
Examples:{ "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true }
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/bulk' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '[ { "displayName":{displayName}, "email":{email}, "username":{username}, "password":{password}, "user_roles":{user_roles} } ]'
Response
- result
The identifier of the response.
The explanation of the
_messageCode_.
Status Code
Success.
Bad Request.
Unauthorized.
Internal Server Error.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/user/currentUserInfo' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
The user name.
Example:
exampleThe authenticator for the user.
Possible values: [
default,external]Example:
externalThe date and time that the user account was created.
Example:
1655162210393The current status of the user's account.
Possible values: [
locked,enabled,disabled]Example:
enabledIndicate whether user is deletable.
Example:
trueThe name that is displayed for this user.
Example:
exampleThe user's unique email address.
Example:
example@ibm.com- Examples:
[ "administrator", "can_provision" ] Group that is returned with a user object's "groups" field.
Internal users will not show up in the get all users request.
Milliseconds from epoch. Tracks when this record was last updated.
Example:
1655162210393- Examples:
[ "manage_vaults_and_secrets", "share_secrets" ] Base64 encoded image.
Example:
iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=The role assigned to the user.
Possible values: [
Admin,User]Example:
AdminThe unique identifier for the user.
Example:
1000331015The roles assigned to the user.
Examples:[ "administrator_role" ]Collection of trivial miscellaneous user attributes.
Examples:{ "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true }
Status Code
Success.
Unauthorized.
Not Found.
{ "authenticator": "external", "created_timestamp": 1655162210393, "current_account_status": "enabled", "deletable": true, "displayName": "example", "email": "example@ibm.com", "group_roles": [ "administrator", "can_provision" ], "groups": [ { "group_id": 10000, "name": "All users", "description": "All users are implicitly part of this group.", "added_separately": true, "created_at": "2022-05-25T22:03:31.193Z", "created_by": "admin", "updated_at": "2022-05-25T22:03:31.193Z", "members_count": 42, "misc": { "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true } } ], "internal_user": false, "last_modified_timestamp": 1655162210393, "permissions": [ "manage_vaults_and_secrets", "share_secrets" ], "profile_picture": "iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=", "role": "Admin", "uid": 1000331015, "user_roles": [ "administrator_role" ], "username": "example", "misc": { "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true } }
Get current user's token expiry
This API allows the current logged in user to view their token expiry details.
GET /usermgmt/v1/user/tokenExpiry
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
The user name.
Example:
example
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/user/{username}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
The user name.
Example:
exampleThe authenticator for the user.
Possible values: [
default,external]Example:
externalThe date and time that the user account was created.
Example:
1655162210393The current status of the user's account.
Possible values: [
locked,enabled,disabled]Example:
enabledIndicate whether user is deletable.
Example:
trueThe name that is displayed for this user.
Example:
exampleThe user's unique email address.
Example:
example@ibm.com- Examples:
[ "administrator", "can_provision" ] Group that is returned with a user object's "groups" field.
Internal users will not show up in the get all users request.
Milliseconds from epoch. Tracks when this record was last updated.
Example:
1655162210393- Examples:
[ "manage_vaults_and_secrets", "share_secrets" ] Base64 encoded image.
Example:
iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=The role assigned to the user.
Possible values: [
Admin,User]Example:
AdminThe unique identifier for the user.
Example:
1000331015The roles assigned to the user.
Examples:[ "administrator_role" ]Collection of trivial miscellaneous user attributes.
Examples:{ "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true }
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
{ "authenticator": "external", "created_timestamp": 1655162210393, "current_account_status": "enabled", "deletable": true, "displayName": "example", "email": "example@ibm.com", "group_roles": [ "administrator", "can_provision" ], "groups": [ { "group_id": 10000, "name": "All users", "description": "All users are implicitly part of this group.", "added_separately": true, "created_at": "2022-05-25T22:03:31.193Z", "created_by": "admin", "updated_at": "2022-05-25T22:03:31.193Z", "members_count": 42, "misc": { "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true } } ], "internal_user": false, "last_modified_timestamp": 1655162210393, "permissions": [ "manage_vaults_and_secrets", "share_secrets" ], "profile_picture": "iVBORw0KGgoAAAANSUhEUgAAAJcAAACXCAYAAAAYn8l5AAAACXBIWXMAAAsSAAALEgHS3X78AAABvklEQVR42u3dMU4CURSG0Qt5IcZYsACiLM3amt5dsAI34i7oiMbExoIQGSbDjLgC4L6CaHHOEm6+5FUv/2jxtZpHxDy4qGm72+1u37hEyqZExGNEPLvFZf0wvEXEg0ukvI7dgGsRF+JCXCAuxIW4QFyIC3GBuBAX4gJxIS7EBeJCXIgLxIW4EBeIi/+q3JebaYmRSySsx4dJE51DZON6upttnCHnpf3pPsOHa88i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLsQF4kJcIC7EhbhAXIgLccEJ5b1vp30cXSJhdxwmrlAR1/L7w6fYpG23993as4i4EBeIC3EhLhAX4kJcIC7EhbhAXIgLcTkB4kJcIC7EhbhAXIgLccFplmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLccFZlmIrWIqtjMtSbJ6lWM8i4kJcIC7EhbhAXIgLcYG4EBfiAnEhLhAX4kJcIC7EhbhAXIgLcYG4+Bu/NXtQOor+IlAAAAAASUVORK5CYII=", "role": "Admin", "uid": 1000331015, "user_roles": [ "administrator_role" ], "username": "example", "misc": { "extAttributes": { "nationality": "United States", "organization": "IBM", "location": "San Jose" }, "realm_name": "openLDAP", "dark_mode": true } }{ "exception": "user details not found", "_messageCode_": "not_found", "message": "The asset is not found", "_statusCode_": 404 }
Update user
This API allows users with an administrator role to update a user's account details via the user's username.
The email field must be unique. An error code 400 will be returned if the email address is already in use.
PUT /usermgmt/v1/user/{username}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Name of the user to update.
Example:
example
Query Parameters
If
true, roles are added to current roles. Otherwise, roles are overwritten.Default:
falseExample:
true
Updated user object.
{
"displayName": "Updated User",
"email": "updateduser@ibm.com",
"user_roles": [
"user_role"
]
}The roles assigned to the user.
The name that is displayed for this user.
The user's unique email address.
curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v1/user/{username}?add_roles={add_roles}' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{ "displayName":{displayName}, "email":{email}, "username":{username}, "user_roles":{user_roles} }'
Response
UID of the updated user.
Example:
1000331015Example:
successExample:
success
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Name of the user to delete.
Example:
example
curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v1/user/{username}' -H 'Authorization: Bearer {token}'
Response
UID of the updated user.
Example:
1000331015Example:
successExample:
success
Status Code
Success.
Unauthorized.
Not Found.
{ "uid": "1000331015", "_messageCode_": "success", "message": "success" }{ "exception": "user details not found", "_messageCode_": "not_found", "message": "The asset is not found", "_statusCode_": 404 }
Renew token
This API allows the current logged in user to renew their Bearer token and session cookie.
POST /usermgmt/v1/user/renewToken
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Token expiry time.
Example:
12
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/renewToken?expiry_time={expiry_time}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
Successful renew token response body.
Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5cExample:
<csrf_token>Example:
successExample:
success
Status Code
Success.
Bad Request.
Unauthorized.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/user/apiKey' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
Successful API key response body.
Example:
<api_key>Example:
successExample:
success
Status Code
Success.
Bad Request.
Unauthorized.
Could not find the user associated with the Bearer token.
Internal Server Error.
{ "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
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Form Parameters
The new password.
Example:
newPasswordThe current password.
Example:
currentPassword
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/changemypassword' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer {token}' --data-urlencode 'password={password},' --data-urlencode 'currentPassword={currentPassword}' curl -k -X POST
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Form Parameters
The user name.
Example:
usernameThe new password.
Example:
newPassword
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/changeuserpassword' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer {token}' --data-urlencode 'username={username}' --data-urlencode 'password={password}'
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Flag to set theme for user profile.
Example:
true
curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v2/own_profile?dark_mode={dark_mode}' -H 'Authorization: Bearer {token}'
Response
Successful setOwnProfile response body.
UID of the updated user.
Example:
1000331015Example:
successExample:
success
Status Code
Success.
Bad Request.
Unauthorized.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Comma-separated string of group identifiers.
Example:
10000,10001Comma-separated string of role identifiers.
Example:
administrator,api_userSet to true to include details about users in this group.
Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/groups?group_identifiers={group_identifiers}&role_identifiers={role_identifiers}&include_members={include_members}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
List of user groups.
Unique ID indentifying the User-Group.
Example:
10000Name of the user group.
Example:
All usersMore detailed information about the user group.
Example:
All users are implicitly part of this group.Creation datetime.
Example:
2022-05-25T22:03:31.193ZUser who created the User-Group.
Example:
adminLast updated datetime.
Example:
2022-05-25T22:03:31.193ZCollection of miscellaneous group attributes.
Examples:{ "isDynamicGroup": false }Stringified number of users in the group
Example:
42Permissions associated with the group.
Examples:[ "administrator", "can_provision" ]
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
[ { "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
{
"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"
]
}Name of the user group.
Example:
example groupMore detailed information about the user group.
Example:
This is a user group description.Unique ID identifying the account that the user group is associated with.
Default:
1000- Examples:
[ "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: Bearer {token}' -d '{ "name": {name}, "description": {description}, "account_id": {account_id}, "role_identifiers": {role_identifiers} }'
Response
Example:
2022-06-20T18:21:21.763ZExample:
adminExample:
This is a user group description.Example:
10001Example:
CreatedExample:
example groupExample:
2022-06-20T18:21:21.763ZExample:
Created
Status Code
Created.
Bad Request.
Unauthorized.
Not Found.
Conflict.
Internal Server Error.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Unique ID indentifying the User-Group.
Example:
10001
{
"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"
]
}Name of the user group.
Example:
example groupMore detailed information about the user group.
Example:
This is a user group description.Unique ID identifying the account that the user group is associated with.
Default:
1000- Examples:
[ "a5d6d89c-4852-4840-b300-4420a3081187", "8dfaf4c4-fe9c-4efa-9aaa-f70570fa5f18" ] - Examples:
[ "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: Bearer {token}' -d '{ "name": {name}, "description": {description}, "account_id": {account_id}, "add_role_identifiers": {add_role_identifiers}, "remove_role_identifiers": {remove_role_identifiers} }'
Response
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Conflict.
Internal Server Error.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Unique ID indentifying the User-Group.
Example:
10001
curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
Status Code
Created.
Unauthorized.
Not Found.
Internal Server Error.
{ "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}/membersRequest
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
User-Group identifier
Example:
10001
Query Parameters
Trueifuser_detailsare required in response.Default:
falseOffset required for pagination.
Max number of records to return in a page.
Example:
25Sorting the user records based upon specific column.
Allowable values: [
uid,username,displayName,email]Default:
uidExample:
uidSorting order either ascending or descending.
Allowable values: [
ASC,DESC]Default:
DESCExample:
DESC
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/members?include_user_details={include_user_details}&offset={offset}&limit={limit}&sort_by={uid}&sort_order={sort_order}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
Successful GET group members response body.
- results
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
{ "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}/membersRequest
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
User-Group identifier.
Example:
10001
Payload containing LDAP groups and/or UIDs.
List of LDAP distinguished names to be added to the group.
Examples:[ "CN=managers,DC=wdp,DC=com", "CN=developers,DC=wdp,DC=com" ]List of groups coming from the IAM's IDP.
Example:
[]List of UIDs to be added to the group.
Examples:[ 1000331015, 1000331016 ]The necessary object to construct the rules based on user attributes.
- attribute_rules
Allowable values: [
and,or]Example:
andThe attribute-based rule object.
Examples:[ { "attribute": "organization", "operator": "equal", "value": "IBM" }, { "attribute": "location", "operator": "not equal", "value": "San Jose" } ]
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/members' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "ldap_groups": {ldap_groups}, "user_identifiers": {user_identifiers}, "attribute_rules": {attribute_rules} }'
Response
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
User-Group identifier.
Example:
10001The user's unique identifier.
Example:
1000331015
curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/members/{uid}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
Status Code
Success.
Unauthorized.
Not Found.
Internal Server Error.
{ "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_rulesRequest
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
User-Group identifier.
Example:
10001
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/membership_rules' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
- results
The attribute-based rule object.
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Rule identifier.
Example:
123
Payload containing group membership rules.
{
"realm_name": "usermgmt_default",
"logical_operator": "and",
"rules": [
{
"attribute": "organization",
"operator": "equal",
"value": "IBM"
},
{
"attribute": "location",
"operator": "equal",
"value": "San Jose"
}
]
}The necessary object to construct membership rules based on user attributes.
- attribute_rules
Allowable values: [
and,or]The attribute-based rule object.
curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v2/groups/membership_rules/{rule_id}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "realm_name": {realm_name}, "logical_operator": {logical_operator}, "rules": {rules} }'
Response
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Rule identifier.
Example:
123
curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v2/groups/membership_rules/{rule_id}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
{
"search_field": "all",
"search_string": "search",
"limit": 10
}Search field to filter by.
Allowable values: [
all,username,name,email,ldap_group]Value for the search field to filter by.
Limit on the number of users to get.
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/ldap/users' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{ "search_field": {search_field}, "search_string": {search_string}, "limit": {limit} }'
Response
Distinguished name (DN) uniquely identifying the LDAP user.
The user's username.
The user's first name.
The user's last name.
The user's display name.
The user's email.
LDAP groups the LDAP user is part of.
The user's LDAP authentication realm.
The user's formatted name.
External attributes from the user's LDAP provider.
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
[ { "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
{
"search_string": "search",
"limit": 10
}Search value to filter groups by.
Limit on the number of groups to get.
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/ldap/groups' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{ "search_string": {search_string}, "limit": {limit} }'
Response
The LDAP group's distinguished name (DN).
The LDAP group's name.
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
[ { "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Pass language for translated content.
Example:
en-US
Query Parameters
Set to true to return count of users assigned to each role.
Default:
falseSet to true to return count of platform users assigned to each role individually.
Default:
falseSet to true to return count of user-groups assigned to each role.
Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/roles?include_users_count={include_users_count}&include_platform_users_count={include_platform_users_count}&include_user_groups_count={include_user_groups_count}' -H 'Accept-Language: en-US' -H 'Authorization: Bearer {token}'
Response
- rows
- doc
The identifier of the response.
The explanation of the
_messageCode_.
Status Code
Success.
Bad Request.
Unauthorized.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Create role object.
{
"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: Bearer {token}' -H 'Content-Type: application/json' -d '{ "description": {description}, "permissions": {permissions} }'
Response
The identifier of the response.
The explanation of the
_messageCode_.
Status Code
Created.
Bad Request.
Unauthorized.
Not Found.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Extension name of the role that needs to be updated.
Example:
22c69856-3e21-4301-b83c-3b226e957d9e
Update role object.
{
"role_name": "Updated Example Role",
"description": "This is an updated example role.",
"permissions": [
"view_platform_health",
"manage_service_instances"
]
}Name of the role.
Description for the role.
Permissions associated with the role.
curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v1/role/{id}' -H 'Authorization: Bearer {token}' -H 'Content-Type: application/json' -d '{ "role_name": {role_name}, "description": {description}, "permissions": {permissions} }'
Response
The identifier of the response.
The explanation of the
_messageCode_.
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Pass language for translated content.
Example:
en-US
Path Parameters
Extension name of the role that needs to be deleted.
Example:
22c69856-3e21-4301-b83c-3b226e957d9e
curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v1/role/{id}' -H 'Accept-Language: en-US' -H 'Authorization: Bearer {token}'
Response
The identifier of the response.
The explanation of the
_messageCode_.
Status Code
Success.
Unauthorized.
Not Found.
{ "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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/attributes' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
- data
- usermgmt_default
- other property
Example:
LocationExample:
simpleExample:
stringExample:
trueExample:
location
The identifier of the response.
The explanation of the
_messageCode_.
Status Code
Success.
Unauthorized.
{ "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" }
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
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Number of days to retain.
Default:
3
curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/events/prune?retention_time={retention_time}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Number of days to retain.
Default:
30
curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v3/metrics/prune?retention_time={retention_time}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
SMTP config for alert monitoring.
curl -k -X PATCH 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/smtp' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{ “registered_emails” : [{registered_emails}] }'
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
The name of the monitor. The default monitor is diagnostics.
Event type, which is used along with the
monitor_type. The following event types are delivered with Cloud Pak for Data:check-pvc-status(records a critical event if a PVC is unbound),check-replica-status(records a critical event if aStatefulSetor 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: Bearer {token}'
Configure monitor schedule
Updates the schedule for the diagnostics monitor or a custom monitor. Monitors must be scheduled as a cron job. By default, the cron job for the default monitor, diagnostics, is scheduled to run every 10 minutes.
PATCH /zen-watchdog/v1/monitoring/config/monitorType
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
The name of the monitor. The default monitor is diagnostics.
Configure zen alert monitor.
curl -k -X PATCH 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/monitorType' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ “schedule” : ”*/10 * * * *” }'
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
The name of the monitor. The default monitor is
diagnostics.Event type. The following event types are delivered with Cloud Pak for Data:
check-pvc-status(records a critical event if a PVC is unbound),check-replica-status(records a critical event if aStatefulSetor deployment has unavailable replicas),check-resource-status(records a warning event if a service has reached the threshold and a critical event if it has exceeded the quota).
Event config.
curl -k -X PATCH 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/eventType' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ <body_params> }'
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Name of the alert type. The default
alert_typeis platform.The severity for which the rules need to be updated. One of the following options:
critcal,warning. You can't configure the alert rules for informational alerts.Allowable values: [
critical,warning]Event type.
Event config.
Determines how to trigger alerts. One of the following options:
immediate,custom. Custom needsalert_countandalert_over_count.A Boolean that determines whether to send an alert when the condition clears. This alert is sent with an severity of info.
Count of events with the severity type.
Count of total events to be referenced.
The number of hours to wait before an alert is reissued. This pauses notifications for this period. Used to avoid spamming the user mailbox.
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: Bearer {token}' -d '{ <body_params> }'
Get SNMP configuration
Retrieves the current SNMP configuration.
GET /zen-watchdog/v1/monitoring/config/snmp
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Form Parameters
The SNMP server host address.
The community string associated with the SNMP connection.
The SNMP server port.
curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/snmp' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}'
Get Slack configuration
Retrieves the current Slack configuration.
GET /zen-watchdog/v1/monitoring/config/slack
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: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Form Parameters
The URL of the webhook to post to a Slack channel.
curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/slack' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}'
Get a list of monitors, profiles, or alert types
Lists all registered monitors and associated event types. The default monitor is diagnostics. Lists all alert types or rules, which define when alerts need to send. The default alert type is platform. Lists all registered alert profiles to enable or disable a certain type of alert (SMTP, SNMP, or Slack). Also provides metadata for the alert methods, including the list of email addresses that are registered to receive alerts.
GET /v1/extensions
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Pass language for translated content.
Example:
en-US
Query Parameters
Set to
zen_alert_monitorto get a list of monitors. Set tozen_alert_typeto get a list of alert types.Identifier of a particular extension.
Array of particular extensions' names.
Type of preference.
Allowable values: [
global,user]Default:
userIdentifier for a particular source.
Query parameter when disabled will return the disabled extensions.
Default:
enabled
curl -k -X GET 'https://{cpd_cluster_host}/v1/extensions?extension_point_id=zen_alert_monitor' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'curl -k -X GET 'https://{cpd_cluster_host}/v1/extensions?extension_point_id=zen_alert_type' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'curl -k -X GET 'https://{cpd_cluster_host}/v1/extensions?extension_point_id=zen_alert_profile' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Store an external vault configuration
Creates an external vault integration by using this API.
POST /v2/vaults
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Query Parameters
Validate vault connection.
Default:
falseValidate vault connection and save.
Default:
false
Sensitive payload to be secured.
{
"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"
}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.
Free-form object containing all connection information for the external vault.
The external vault type, either the
cyberark_aam_certorhashicorp_token.A short description for your vault.
The object to hold test secret reference information. If the query parameter
vaildate=trueis set, integration with the external vault is validated. To validate and save, use the query parametervaildate_and_save=true.
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/vaults' -H 'Accept: application/json' -H 'Authorization: Bearer {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" }'
Retrieve details about external vault integrations
Retrieves details about external vault integrations for user.
GET /v2/vaults
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Query Parameters
The number of vaults to skip before starting to collect the result set.
Default:
0The number of vaults to return.
Default:
50Preview secrets.
Default:
falseSort by the field (such as sort=display_name or sort=-display_name for descending). The supported sort columns are:
vault_name,owned_by,created_by,uploaded_at,total_secrets.Comma-separated provider names (such as CyberArk AAM, HashiCorp).
A name for your vault. This name must be unique across all the vaults that you own and that are currently stored in the vault.
Match on all or any criteria, possible values.
Allowable values: [
any,all]Default:
anyIf
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: Bearer {token}'
Response
Offset is used to determine how many vaults to skip over, given the order of the collection. If it is not specified the default is 0.
Limit is used to determine how many vaults are returned. If it is not specified the default is 20.
Total number of vaults.
Vault collection.
Status Code
Success.
Unauthorized.
Not Found.
Internal Server Error.
{ "limit": 2, "offset": 0, "total_count": 4, "vaults": [ { "created_at": "2021-05-18T02:19:37.237302Z", "created_by": "admin", "description": "creating sample vault test-hashicorp-token-vault-0", "invalid_auth": false, "invalid_owner": false, "owned_by": "admin", "provider_name": "Hashicorp - Token Authentication", "secret_preview": "test-hashicorp-token-vault-0-secret-0", "total_secrets": 1, "updated_at": "2021-05-18T02:19:37.23523Z", "vault_name": "test-hashicorp-token-vault-0", "vault_type": "hashicorp_token", "vault_urn": "1000330999:test-hashicorp-token-vault-0" }, { "created_at": "2021-05-18T02:19:37.258828Z", "created_by": "admin", "description": "creating sample vault test-cyberark-aam-cert-vault-0", "invalid_auth": false, "invalid_owner": false, "owned_by": "admin", "provider_name": "CyberArk AAM - Cert Authentication", "secret_preview": "test-cyberark-aam-cert-vault-0-secret-0", "total_secrets": 1, "updated_at": "2021-05-18T02:19:37.257123Z", "vault_name": "test-cyberark-aam-cert-vault-0", "vault_type": "cyberark_aam_cert", "vault_urn": "1000330999:test-cyberark-aam-cert-vault-0" } ] }
Retrieve a vault
Retrieves the details for a vault that is specified by the vault's uniform resource name.
GET /v2/vaults/{vault_urn}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
The path parameter that the vaults micro-service uses to identify and associate the vault with the user. 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: Bearer {token}'
Update external vault configuration
Updates configuration details of an external vault, response does not includes sensitive data.
PATCH /v2/vaults/{vault_urn}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
The path parameter that the vaults micro-service uses to identify and associate the vault with the user. This parameter uses a specific notation:
<creator uid>:<vault_name>.
Query Parameters
Validate vault connection.
Default:
falseValidate vault connection and save.
Default:
false
Sensitive payload to be secured.
Short description about the vault being configured for the user.
The object that contains the sensitive details for connecting to the external vault.
The object to hold test secret reference information. If the query parameter
vaildate=trueis set, integration with the external vault is validated. To validate and save use the query parametervaildate_and_save=true.
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: Bearer {token}' -d '{ "description": "<description>", "details": <details>, "test_data": <test-data> }'
Delete external vault integration
Deletes a specific external vault integration for user. Note: Deleting a vault deletes all of its associated secrets.
DELETE /v2/vaults/{vault_urn}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
Vault ID.
curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v2/vaults/<vault_urn>' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Initiate the transfer of ownership of a vault
Initiates the transfer of ownership of a vault and any secrets in the vault to a different owner.
POST /v2/vaults/{vault_urn}/transfersRequest
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
The path parameter that the vaults micro-service uses to identify and associate the vault with the user. This parameter uses a specific notation:
<creator uid>:<vault_name>.
Query Parameters
If
true, transfer re-submission will be executed only if allowed transfer duration is over.Default:
false
Sensitive payload to be secured.
The new owner's unique identifier.
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/vaults/<vault-urn>/transfers' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ new_owner_uid": "1000331007" }'
Response
Status Code
Success.
Transfer vault request accepted.
Bad Request.
Unauthorized.
Forbidden.
Not Found.
Conflict.
Internal Server Error.
{ "value": { "metadata": { "created_at": "2022-02-24T21:36:45.677Z", "created_by": "user4", "description": "Create HashiCorp vault for transferring vault ownership tests synchronously.", "invalid_auth": true, "invalid_owner": false, "owned_by": "user7", "owner_uid": 1000331007, "provider_name": "Hashicorp", "secret_preview": "vault-hashi-uc-trans-vault-secret-1vault-hashi-uc-trans-vault-secret-2vault-hashi-uc-trans-vault-secret-3", "total_secrets": 3, "updated_at": "2022-02-24T21:36:45.677Z", "vault_name": "vault-hashi-uc-trans-vault", "vault_type": "hashicorp_token", "vault_urn": "1000331031:vault-hashi-uc-trans-vault" } } }
Transfer vault to user
Authenticates the external vault and transfers it to the new owner.
PATCH /v2/vaults/{vault_urn}/transfersRequest
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
Vault ID.
Sensitive payload to be secured.
The object that contains the sensitive details for connecting to the external vault.
The object to hold test secret reference information. If the query parameter
vaildate=trueis set, integration with the external vault is validated. To validate and save use the query parametervaildate_and_save=true.
curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/v2/vaults/<vault-urn>/transfers' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "vault_address": "<vault-address>", "access_token": "<token>" }'
Response
Status Code
Success.
Success.
Bad Request.
Unauthorized.
Forbidden.
Not Found.
Conflict.
Internal Server Error.
{ "value": { "metadata": { "created_at": "2022-02-24T21:36:45.677Z", "created_by": "user4", "description": "create hashicorp vault for transferring vault ownership tests synchronously", "invalid_auth": true, "invalid_owner": false, "owned_by": "user7", "owner_uid": 1000331007, "provider_name": "Hashicorp", "secret_preview": "vault-hashi-uc-trans-vault-secret-1vault-hashi-uc-trans-vault-secret-2vault-hashi-uc-trans-vault-secret-3", "total_secrets": 3, "updated_at": "2022-02-24T21:36:45.677Z", "vault_name": "vault-hashi-uc-trans-vault", "vault_type": "hashicorp_token", "vault_urn": "1000331031:vault-hashi-uc-trans-vault" } } }
Store secret or reference
Stores and secures a secret or secret reference to an external vault in an internal vault.
POST /v2/secrets
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Query Parameters
Validate secret reference.
Default:
falseValidate secret reference and save.
Default:
false
Sensitive payload to be secured.
{
"secret_name": "generic-secret,",
"description": "This is a generic secret.",
"secret": {
"generic": {
"my_secret": "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ"
}
},
"type": "generic,",
"vault_urn": "0000000000:internal"
}A name for your secret. This name must be unique across all the secrets that you own and that are currently stored in all vaults. It can contain a maximum of 110 characters.
Any free-form object (JSON). This parameter is schema-less, which means you can enter any type of information that is entered as valid key-value pairs. What you send out comes back when you retrieve your secret.
ID of user vault.
A short description for your secret.
Type of the secret.
Allowable values: [
certificate,credentials,generic,key,token,kerberos_credentials]Default:
generic
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/secrets' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "secret_name": "generic-secret", "description": "This is my generic secret", "secret": { "generic": { "my_secret" : "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ" } }, "type": "generic", "vault_urn": "0000000000:internal" }'
Get a list of all secrets
Gets a list of all secrets that are stored in a deployment.
GET /v2/secrets
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Query Parameters
The number of secrets to skip before starting to collect the result set.
Default:
0The number of secrets to return.
Default:
50Includes preview of secrets.
Default:
falseSort by the field (for example: sort=secret_name or sort=-secret_name for descending order).\n The supported sort columns include:
secret_name,type,description,created_by,vault_name,updated_at.The type of secret. Vault support per type:
generic(Internal, HashiCorp),certificate(Internal, CyberArk, HashiCorp),credentials(Internal, CyberArk, HashiCorp),key(Internal, CyberArk, HashiCorp),token(Internal, HashiCorp)Secret name.
Match on all or any criteria, possible values.
Allowable values: [
any,all]Default:
anyIf 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: Bearer {token}'
Response
The number of secrets to skip before the API starts to collect the result set. If it is not specified the default is 0.
Limit is used to determine how many secrets are returned. If it is not specified the default is 20.
Total number of secrets.
Secret collection.
Status Code
Success.
Unauthorized.
Internal Server Error.
No Sample Response
Retrieve the details for a secret
Retrieves the details of a secret for a vault specified by a uniform resource name.
GET /v2/secrets/{secret_urn}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
Query Parameters
The
exclude_secret_dataparameter 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: Bearer {token}'
Update or refresh stored secret
Updates a secret or secret reference to an external vault. Note: You can update the secret itself and its description, but you cannot update the secret_name, vault_name, or type. These fields are immutable and cannot be edited.
PATCH /v2/secrets/{secret_urn}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
Query Parameters
Validate secret reference.
Default:
falseValidate secret reference and save.
Default:
false
Sensitive payload to be secured.
{
"description": "<description>",
"secret": "<secret>"
}A short description of your secret.
Any free-form object (JSON). This parameter is schema-less, which means you can enter any type of information that is entered as valid key-value pairs. What you send out comes back when you retrieve your secret.
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets/<secret_urn>' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "description": "<description>", "secret": <secret> }'
Delete a secret from vault
Deletes an existing secret or secret reference to an external vault.
DELETE /v2/secrets/{secret_urn}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v2/secrets/1000330999:oracle-db-login-credentials' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Share a secret
Shares a secret or a secret reference to an external vault to other users and groups.
POST /v2/secrets/{secret_urn}/membersRequest
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
List of users or groups.
The list of users that can access a secret.
The list of groups that can access a secret.
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/secrets/<secret_urn>/members' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "users": [ { "username": <username>, "uid": <uid> } ], "groups": [ { "group_name": <group-name>, "group_id": <group-id> } ] }'
Get secret members
Retrieves a list of all the shared members for a secret or a secret reference to an external vault.
GET /v2/secrets/{secret_urn}/membersRequest
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
Query Parameters
The number of secret members to skip before starting to collect the result set.
Default:
0The 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: Bearer {token}'
Response
Offset is used to determine how many secret members to skip over, given the order of the collection.
Limit is used to determine how many secret members are returned.
Total number of secrets.
Secret members.
Status Code
Success.
Bad Request.
Unauthorized.
Forbidden.
Not Found.
Internal Server Error.
No Sample Response
Share or unshare a secret
Adds or removes users' or groups' access to secret or a secret reference to an external vault.
PUT /v2/secrets/{secret_urn}/membersRequest
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
List of users or/and groups.
The list of users and groups that can access a secret.
The list of users and groups can no longer access a secret.
curl -k -X PUT 'https://{cpd_cluster_host}/zen-data/v2/secrets/<secret_urn>/members' -H 'Authorization: Bearer {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" } ] } }'
Unshare secret
Removes users' or groups' access to secret or a secret reference to an external vault.
DELETE /v2/secrets/{secret_urn}/membersRequest
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
List of users or/and groups.
The list of users that can access a secret.
The list of groups that can access a secret.
curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v2/secrets/1000330999:oracle-db-login-credentials/members' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "users": [ { "username": "user2", "uid": "1000331002" } ], "groups": [ { "group_name": "provision_group", "group_id": "10002" } ] }'
Retrieve all my secrets
Returns a list of secrets that you stored in the internal vault. Note: The list does not contain any sensitive information. It contains identifiers of the secrets and metadata only.
GET /v2/secrets/bulk
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Query Parameters
Comma-separated secret_urns.
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets/bulk?secret_urns=secret-urn-1,secret-urn-2,secret-urn-3' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Retrieve a secret
Returns a secret that you stored in the internal vault for a specified reference. This method returns the entire secret payload in the same manner that it was stored in the vault.
POST /v2/serviceInstance/token
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
If this is set to true, then cookie with that instance ID is generated.
Duration (in minutes) the token is valid.
Default:
20
curl -k -X POST 'https://{cpd_cluster_host}/v2/serviceInstance/token' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "serviceInstanceID": {serviceInstanceID} }'
Response
[DO NOT USE] TO BE DEPRECATED
The jwt encoded token. The decoded value is shown here in the example.
Examples:This value is a jwt encoded string, below is the example of decoded value. { "custom": { "ModuleName": "streams", "Role": "Admin", "ServiceInstanceDisplayName": "string", "ServiceInstanceID": "1547441124", "ServiceInstanceUserName": "user999", "ZenDisplayName": "admin", "ZenUID": "999", "ZenUsername": "admin" }, "exp": 1548127840, "iat": 1548126640, "iss": "ICPD" }
Status Code
Success.
Error.
Unauthorized.
Not Found.
Conflict.
Internal Server Error.
No Sample Response
Get a list of custom cards
Retrieves the properties for the custom cards that you can update.
GET /v1/custom_cards
Create or replace a custom card
Creates a custom card or replaces an existing custom card. You must include the card definition as a JSON string in the HTTP request body. The definition specifies the structure and the content of the card.
PUT /v1/custom_cards/{key}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
The name of the card that you want to create or replace. The string must be unique. If a custom card with the specified key does not exist, the custom card is created, otherwise the existing custom card is replaced.
Update role object.
Specifies the permissions that a user needs to see the card. The array must have at least one permission. If the array has no permissions parameter, the card is shown to everyone. It is an array of user permissions from the Cloud Pak for Data platform.
Defines the position of the card. The value must be in the range 1 - 50.
Possible values: 1 ≤ value ≤ 50
Example:
1The display name for the card. The string must be 40 characters or less.
Example:
Disk usageDefines the display type of the card. The
template_typeparameter must be one of the following:bar,big_number,content_block,donut,list,number_list,text_list).Example:
big_numberAn array of authorized roles from Cloud Pak for Data platform that shows the card to a user having any of the listed roles.
Provides data to the card. You must provide either a data_url object or a data object. The data object is an object that populates data in the card. The properties of the object must match the type of template defined. The expected structure for each template_type parameter is in the examples.
Defines the URL that the user navigates to when they click "View details". If this parameter is not defined, the card does not display a "View details" link.
Helps users understand the purpose of the card. The string must be 200 characters or less.
Example:
The card gives details about loans and depositsIdentifiers that can be defined by the services for use in their UI components.
Example:
566c3a42-610c-48e8-a879-9b175b7a52ccSpecifies the target attribute or the name of the window. The following values are supported: empty or not provided (the URL gets loaded on the current page by default),
_blank(URL is loaded into a new window or tab every time),name(the name of the window where the URL is loaded and the name does not specify the title of the new window).Example:
https://foo.barThe interval in seconds at which the content is refreshed by the source.
Default:
0Example:
5
curl -k -X PUT 'https://{cpd_cluster_host}/zen-data/v1/custom_cards' -H 'Accept-Language: en-US' -H 'Accept: application/json' -H 'Authorization: Bearer {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
Message code.
Message.
Status Code
Success.
Bad Request.
Unauthorized.
Forbidden.
Not Found.
Internal Server Error.
{ "_messageCode_": "success", "data": { "id": 537163840404062200, "name": "os_vulnerabilities", "title": "Open source vulnerabilities", "description": "", "drilldown_url": "", "order": 12, "template_type": "big_number", "data_url": "", "empty_state": {}, "source_url": "", "refresh_rate": 0, "data": { "big_number_data": { "metric": 55, "sub_text": "Increase since last month", "prefix": "ArrowUp32", "suffix\"": "%", "footer_1": "867 Total vulnerabilities", "footer_2": "AskPQL 2.3 package most at risk" } } } }
Update an existing card
Updates the information that is displayed on an existing card.
PATCH /v1/custom_cards/{key}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
The name of the card that you want to update.
Update role object.
Specifies the permissions that a user needs to see the card. The array must have at least one permission. If the array has no permissions parameter, the card is shown to everyone. It is an array of user permissions from the Cloud Pak for Data platform.
An array of user roles from Cloud Pak for Data platform.
Defines the position of the card. The value must be in the range 1 - 50.
Possible values: 1 ≤ value ≤ 50
Example:
2The display name for the card. The string must be 40 characters or less.
Example:
Disk usageDefines the display type of the card. The
template_typeparameter must be one of the following:bar,big_number,content_block,donut,list,number_list,text_list).Example:
donutProvides data to the card. You must provide either a data_url object or a data object. The data object is an object that populates data in the card. The properties of the object must match the type of template defined. The expected structure for each
template_typeparameter is in the examples.Defines the URL that the user navigates to when they click View details. If this parameter is not defined, the card does not display a "View details" link.
Helps users understand the purpose of the card. The string must be 200 characters or less.
identifiers that can be defined by the services for use in their UI components.
Example:
566c3a42-610c-48e8-a879-9b175b7a52ccSpecifies the target attribute or the name of the window. The following values are supported: empty or not provided (the URL gets loaded on the current page by default),
_blank(URL is loaded into a new window or tab every time),name(the name of the window where the URL is loaded and the name does not specify the title of the new window).Example:
https://foo.barThe interval in seconds at which the content is refreshed by the source.
Default:
0Example:
5
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: Bearer {token}' -d '{ "title": "Disk usage" }'
Response
Message code.
Message.
Status Code
Success.
Bad Request.
Unauthorized.
Forbidden.
Not Found.
Internal Server Error.
{ "_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 } }
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
The name of the custom card that you want to delete.
curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v1/custom_cards/os_vulnerabilities' -H 'Accept-Language: en-US' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Create a volume instance
Creates a volume instance that can be used to host data files. The volume instance can be consumed by other services. This method can also be used to automatically start a file server on a volume instance. 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 /v3/service_instances
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
ServiceInstance metadata artifact that needs to be added to the database.
{
"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"
}Type of the add-on.
The name to display for the volume in the web client. The string should be 25 characters or less and contain only lowercase alphanumeric characters and dashes. This
display_nameis used to derive the new PVC name. It will bevolumes-**display_name**-pvc.The Red Hat OpenShift project (namespace) where the Cloud Pak for Data control plane is installed.
Version of the add-on.
Default:
falseThis object will be forwarded to service provider without saving to database.
curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "addon_type": "volumes", "addon_version": "-", "create_arguments": { "metadata": { "volume_type": "NEW_PVC", "storageClass": "nfs-client", "storageSize": "1Gi", "mount_path": "<mount-path>" } }, "namespace": "zen", "display_name": "volumes-sample-1" }'curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "addon_type": "volumes", "addon_version": "-", "create_arguments": { "metadata": { "volume-type": "EXISTING_PVC", "existing_pvc_name": "user-home-pvc", "supplemental_groups": [8888, 1111] "mount_path": "<mount-path>" } }, "namespace": "zen", "display_name": "existing-pv-sample-1" }'curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "addon_type": "volumes", "addon_version": "-", "create_arguments": { "metadata": { "volume_type": "EXTERNAL_NFS", "nfs_server_address": "9.30.10.10", "nfs_export_path": "/mnt/nfs_shares/", "mount_path": "/mnts/data/" "supplemental_groups": [8888, 1111] } }, "namespace": "<control-plane-namespace>", "display_name": "<display-name>" }'curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "addon_type": "volumes", "addon_version": "-", "create_arguments": { "metadata": { "volume_type": "SMB_CIFS", "cifs_server_address": "9.30.94.140", "cifs_export_path": "private", "mount_path": "/mnts/samba", "cifs_username": "admin" } }, "namespace": "zen", "display_name": "samba-doc-test", "transient_fields": { "cifs_password": "password" } }'curl -k -X POST 'https://{cpd_cluster_host}/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: Bearer {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>" }'
Get a service instance collection
Retrieves the list of service instances that you have access to.
GET /v3/service_instances
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Query Parameters
If set to true returns all volume instances. This parameter can be used by an Administrator only.
Type of the add-on.
Exclude addon type volumes in the collection.
Default:
falseVersion of the add-on, this needs to be used with
addon_type.Name of the instance to query.
Category of the add-on, this cannot be used with other parameters.
The number of service instances to skip before starting to collect the result set.
The number of service instances to return.
Example:
20
curl -k -X GET 'https://{cpd_cluster_host}/v3/service_instances?addon_type=volumes' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
Offset is used to determine how many instances to skip over, given the order of the collection. If it is not specified the default is 0.
Limit is used to determine how many instances are returned. If it is not specified the default is 20.
Total number of instances.
Service instance collection
- service_instances
Role of user.
Service instance ID.
Service instance creation time.
Service instance last updated time.
Version of the add-on.
The name to display for the volume in the web client. The string should be 25 characters or less and contain only lowercase alphanumeric characters and dashes.
Type of the add-on.
Lifecycle status used by broker.
Possible values: [
TRIGGERED,PROVISION_IN_PROGRESS,PROVISIONED,FAILED,DEPROVISION_INITIATED,DEPROVISION_IN_PROGRESS,DEPROVISIONED,DEPROVISION_FAILED,UPDATE_INITIATED,UPDATE_IN_PROGRESS,PROVISIONED_UPDATED,UPDATE_FAILED,UNKNOWN,UPGRADED,UPGRADE_FAILED,UPGRADE_IN_PROGRESS]The Red Hat OpenShift project (namespace) where the Cloud Pak for Data control plane is installed.
This field is optional. Can be used by services such as Db2 for z/OS.
Connection information for the provider.
Free-form object that includes mandatory fields required to create service instance, these are persisted to metastore database.
Description of the service instance.
Free-form object that includes non-mandatory fields used by service provider, these are persisted to metastore database.
Service instance related information sent to service provider during instance management.
Includes additional information used while creating instance.
Number of users assigned to service instance.
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
No Sample Response
Create a volume
Creates a volume instance. Creates a volume instance that can be used to host data files, manage access to Cloud Pak for Data users, and be consumed by other services. You must include the volume instance definition as a JSON string in the HTTP request body. Can be initiated only by a user with the Create service instances permission.
POST /v1/volumes
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
VolumeInstance metadata artifact that needs to be added to the database.
Type of the add-on.
The name to display for the volume in the web client. The string should be 25 characters or less and contain only lowercase alphanumeric characters and dashes. This
display_nameis used to derive the new PVC name. It will bevolumes-**display_name**-pvc.The Red Hat OpenShift project (namespace) where the Cloud Pak for Data control plane is installed.
Version of the add-on.
Default:
falseThis object will be forwarded to service provider without saving to database.
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v1/volumes' -H 'Content-Type: application/json' -H 'Authorization: Bearer {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" }'
Get a list of volume instances
Retrieves the list of volumes that you have access to.
GET /v1/volumes
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
If set to true returns all volume instances. This parameter can be used by an Administrator only.
ID of the volume.
Query by volume name.
Query by namespace.
The number of volumes to skip before starting to collect the result set.
Default:
0The number of volumes to return.
Default:
20
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/volumes' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/volumes?display_name=<insert-volume-name>' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/volumes?fetch_all_instances=true' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Response
Offset is used to determine how many instances to skip over, given the order of the collection. If it is not specified the default is 0.
Limit is used to determine how many instances are returned. If it is not specified the default is 20.
Total number of instances.
Service instance collection
- service_instances
Role of user.
Service instance ID.
Service instance creation time.
Service instance last updated time.
Version of the add-on.
The name to display for the volume in the web client. The string should be 25 characters or less and contain only lowercase alphanumeric characters and dashes.
Type of the add-on.
Lifecycle status used by broker.
Possible values: [
TRIGGERED,PROVISION_IN_PROGRESS,PROVISIONED,FAILED,DEPROVISION_INITIATED,DEPROVISION_IN_PROGRESS,DEPROVISIONED,DEPROVISION_FAILED,UPDATE_INITIATED,UPDATE_IN_PROGRESS,PROVISIONED_UPDATED,UPDATE_FAILED,UNKNOWN,UPGRADED,UPGRADE_FAILED,UPGRADE_IN_PROGRESS]The Red Hat OpenShift project (namespace) where the Cloud Pak for Data control plane is installed.
This field is optional. Can be used by services such as Db2 for z/OS.
Connection information for the provider.
Free-form object that includes mandatory fields required to create service instance, these are persisted to metastore database.
Description of the service instance.
Free-form object that includes non-mandatory fields used by service provider, these are persisted to metastore database.
Service instance related information sent to service provider during instance management.
Includes additional information used while creating instance.
Number of users assigned to service instance.
Status Code
Success.
Bad Request.
Unauthorized.
Forbidden.
Not Found.
Internal Server Error.
No Sample Response
Get a list of persistent volume claims by namespace cluster
Retrieves a list of persistent volume claims based on a specified namespace. available in this ICP4Data cluster.
GET /v2/persistentvolumeclaims/{namespace}Update a volume
Updates a volume description. If it is an external SMB volume, this API can be also used to update the volume SMB/CIFS credentials.
PATCH /v1/volumes/{display_name}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Name of the volume instance.
curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/v1/volumes/{display_name}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "description":"<new-description>", "cifs_username":"<new-cifs-username>", "cifs_password":"<new-cifs-password>" "supplemental_groups": [<group-id>, <group-id2>, ...] }'
Delete a volume
Deletes a volume instance and removes users' access to the volume. Important: The data inside of the volume is not deleted and services can continue to use the volume until a Red Hat OpenShift project administrator removes the persistent volume claim to reclaim the storage. The reclaim policy that is specified in the storage class determines what happens when the persistent volume claim is deleted.
DELETE /v3/service_instances/{instance_id}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Unique ID that is used to identify each transaction.
Path Parameters
Service Instance Identifier
Query Parameters
Set to true if the instance needs to be force deleted and bypass the default defensive checks pertaining to the service status.
curl -k -X DELETE 'https://{cpd_cluster_host}/v3/service_instances/{instance_id}' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Get all namespaces
Retrieves all the namespaces available in this Cloud Pak for Data deployment.
GET /v2/namespaces
Give access to a volume
Gives one or more users access to a volume instance. By default, only the user who created the volume instance is an administrator. You must include the volume instance ID as a JSON string in the HTTP request body. You can get the volume instance ID by using /zen-data/v3/service_instances.
POST /v2/serviceInstance/users
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Form Parameters
- users
- groups
curl -k -X POST 'https://{cpd_cluster_host}/v2/serviceInstance/users' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer {token}' -d '{ "serviceInstanceID":"<volume-instance-ID>", "users":[ { "display_name":"<display-name-of-user>", "role":"<access-level>", "uid":"<uid-of-user>", "username":"<username-of-user>" } ] }'
Revoke access to a volume
Revokes a user's access to the specified volume instance. You must include the volume instance ID as a JSON string in the HTTP request body. You can get the volume instance ID by using /zen-data/v3/service_instances.
DELETE /v2/serviceInstance/users
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Arrays of UID to delete.
Array of UIDs to delete.
Arrays of group IDs to delete.
curl -k -X DELETE 'https://{cpd_cluster_host}/v2/serviceInstance/users' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "serviceInstanceID":"<volume-instance-ID>", "users":[ "<uid-of-user>" ] }'
Get a list of users with access to a volume
Retrieves the list of users who have access to the specified volume. The role of each user is also returned.
GET /v2/serviceInstance/users
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Service Instance ID of the service.
Include profile picture or not.
Default:
falseRoles to query.
Includes group users or not.
Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/v2/serviceInstance/users?sID=<volume_instance_id>' -H 'Accept: application/json' -H 'Authorization: Bearer {token}'
Change a user's role on a volume
Changes the user's role (access level) on the specified volume. You must include the volume instance ID as a JSON string in the HTTP request body. You can get the volume instance ID by using /zen-data/v3/service_instances. Note: Can be used only by the administrator of the service instance
PATCH /v2/serviceInstance/users/role
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
ServiceInstance metadata artifact that needs to be added to the database.
curl -k -X PATCH 'https://{cpd_cluster_host}/v2/serviceInstance/users/role' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {token}' -d '{ "serviceInstanceID":"<volume-instance-ID>", "roles":[ { "uid":"<uid-of-user>", "newRole":"<new-access-level>" } ] }'
Start a file server with a persistent volume
Starts a service that contains a file server that supports upload, delete, list, and get operations on files.
POST /v1/volumes/volume_services/{display_name}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
The display name of the volume instance. You can get the volume instance display name by using
/zen-data/v3/service_instances.
Volume metadata.
The file server started is run as this UID. This user needs to be within range 1000320900 to 1000361000 if
cpd-user-sccis used.
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v1/volumes/volume_services/<display_name>' -H 'Content-Type: application/json' -H 'Authorization: Bearer {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: Bearer {token}' -d '{ "run_as_user": <uid-of-user> }
Stop a file server on a volume
Stops the Volume File Server REST service on the specified volume instance. You can stop the file server to suspend unnecessary processing when the file server is not needed. Stopping the file server releases the compute resources that are used by the file server. Note: The data in the volume is not deleted.
DELETE /v1/volumes/volume_services/{display_name}Monitor a file server
Monitor a volume's file server status. If the file server in unavailable, you get a 502 Bad Gateway error.
GET /v1/monitor
Upload file to the volume
Upload a file or create a directory (if no file provided to upload) into the volume. You must specify the target directory for the file on the volume and the path to the source file on the local file system.
PUT /v1/volumes/files/{file_path}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Path leading upto where the file is uploaded in the volume. This must be url-encoded.
Query Parameters
The default value is
false. Set the parameter totrueto extract the contents of.zip,.tar,.tar.gz, or.tgzfiles to the specified directory. You can also upload binary-like files, that is, files that do not have a file extension.Default:
falseSet the
make_executableparameter totrueto 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. Themake_executableparameter 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:
falseSet to
trueif and only if the name infile_pathis not to be validated or sanitized.Default:
falseThe
keep_root_dirparameter takes effect when uploading.zipfile andextractis set to true. Ifkeep_root_diris set to true, then the extracted file structure will be the exactly same as the original file (root directories will be kept). If the flag is not set or set to false, then the extracted contents will be the same as the old behavior (root directories are removed).Default:
false
Form Parameters
File to be uploaded. If this field is absent then a directory with the file-path is created.
curl -k -X PUT 'https://{cpd_cluster_host}/zen-volumes/{display_name}/v1/volumes/files/{directory_path}?make_executable=true' -H 'Authorization: Bearer {token}' -H 'Content-Type: multipart/form-data' -F upFile=''
Download a file from a volume
Downloads the specified file from the specified volume. You can download a file or an archived directory in the name of your choice. Pass the file name of your choice in the optional override_file_name parameter. You can use the dry_run parameter to check if the asset at the target_file_path exists and return some useful metadata in the response header about the asset. You can also download an entire directory as an archive. Pass the archive type in as the value for the compress parameter in the request. If you issue this command from a web browser, the download prompt is displayed.
GET /v1/volumes/files/{file_path}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Path leading upto where the file is uploaded in the volume. This must be url-encoded.
Query Parameters
Set to true to probe the file/directory without actually downloading it.
Default:
falsePass a string here to override the name of the file downloaded.
Specify archive value to compress and download directory.
Allowable values: [
zip,tar,tar.gz]
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: Bearer {token}'
Delete a directory or file on a volume
Deletes the specified file or directory on the specified volume.
DELETE /v1/volumes/files/{file_path}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
Path leading upto where the file is uploaded in the volume. This must be url-encoded.
curl -k -X DELETE 'https://{cpd_cluster_host}/zen-volumes/<display_name>/v1/volumes/files/<target_path>' -H 'Authorization: Bearer {token}'
Copy, move, or rename a file or directory in a volume
Copies, moves, or renames files and directories within a volume.
PUT /v1/volumes/objects/copy
Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Query Parameters
Set to
falseif you do not want to retain a copy of the object at thesource_path(equivalent to amvinUNIX). This value defaults to true, which keeps the object at thesource_path.Default:
trueSet to
trueifdestination_pathin the request body includes the name the object is to be copied as. This value defaults tofalse. That is, the object will be copied to thedestination_pathwith the same name as in thesource_path, creating any directories specified in thedestination_path.Default:
falseSet to
trueif you want to force replace a conflicting object at thedestination_path. This value defaults tofalse. 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
Source path of file or directory relative to
volume_namedirectory.Destination path of file or directory relative to
volume_namedirectory.
curl -k -X PUT 'https://{cpd_cluster_host}/zen-volumes/<volume_name>/v1/volumes/objects/copy' -H 'Authorization: Bearer {token}' -H 'Content-Type: application/json' -d '{ "source_path": "foo/bar", "destination_path": "baz" }
Get a list of the directories and files on a volume
Retrieves the list of all directories and files on the specified volume. You can use the recursive parameter to list contents from the <directory_path> recursively. The API supports a boolean query parameter tree. If set to true, the API returns the contents as a tree structure representing the actual directory structure. To use the tree option, you must set recursive to true. You can also optionally use the include_details query parameter to list the contents of the <directory_path> as an array of objects and their metadata.
GET /v1/volumes/directories/{directory_path}Request
Custom Headers
Authorization: Bearer <token>
Examples:Bearer <token>
ZenApiKey <token>
Path Parameters
The directory for which you want to display the contents. If you are referring to a nested directory, use URL encoding. For example, to create a reference to a directory called
Shared files/analytics projects, enter:Shared%20files%2Fanalytics%20projects.
Query Parameters
The default value is
false. Set the parameter to true to list the contents of the specified directory path recursively.Default:
falseThe default value is
false. Set the parameter totrueto have the API contents returned as a tree structure that represents the actual directory structure.Default:
false(To Be Deprecated Soon) Set to true if you want the response to indicate the type of entity (for example: file or directory)
Default:
falseIf set to
true, the API lists the contents from thedirectory_pathas an array of objects with each object containing certain metadata information about the entity (file/directory) encountered at that location. The default isfalse. 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: Bearer {token}'