Introduction
As an administrator, you are responsible for determining and implementing the best approach for authenticating and managing the Cloud Pak for Data platform.
You can perform the following tasks by using the Cloud Pak for Data REST API:
- Manage user and user group permissions
-
A Cloud Pak for Data administrator can create and manage roles, which grant permissions to users and groups on the platform.
-
A user can have multiple roles. The roles can be assigned directly to a user or can be assigned to the user through a user group. If a user has multiple roles, the user has all of the permissions from all of the roles that are assigned to them.
-
User groups make it easier to manage many users with similar access requirements. For example, if you know that 20 different users are going to collaborate on a project and they all need the Data steward role, you can add them to a group that is assigned the Data steward role. If a member of the group leaves the company, you can remove the user from the group, rather than look for and update all of the assets that the user has access to.
- Create and manage user profiles
-
Authenticated users can perform tasks such as updating their own user-profile information, generating an API key, or changing their password.
-
A Cloud Pak for Data administrator with the
administrator
ormanage_users
permissions can also create, update, or delete user-profiles. - Manage service instances
-
A Cloud Pak for Data administrator with the
Create service instances
permission can create, retrieve, and delete service instances. - Configure monitors and alerts
-
A Cloud Pak for Data administrator can browse generated events and configure monitors and alerts.
- Create custom cards for the home page
-
Administrators can create custom cards to display key performance indicators on the Cloud Pak® for Data home page.
- Manage secrets and vaults
-
Authenticated users can safeguard credentials and secrets with access control and audit logging by using vaults.
- Manage persistent volume instances
-
Administrators with the
Create service instances
permission can create and manage persistent volume instances on your existing Cloud Pak® for Data storage devices.
Using Authorization: ZenApiKey token
With a platform API key, you can access everything that you would typically be able to access when you log in to the Cloud Pak for Data web client.
To generate a platform API key through the user experience:
- 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.
Using Authorization: Bearer token
If Identity and Access Management (IAM) are not enabled, you can generate a token by using your username and password against the Get authorization token endpoint.
If IAM is enabled, you can generate a token by using your username and password against the /idprovider/v1/auth/identitytoken
endpoint.
Generating an access token by using the Get authorization token endpoint. The response includes a token
property.
Replace {cpd_cluster_host}
with the details for the service instance. Replace {username}
and {password}
with your IBM Cloud Pak for Data credentials.
curl -k -X POST "https://{cpd_cluster_host}/icp4d-api/v1/authorize" \
-d "{\"username\":\"{username}\",\"password\":\"{password}\"}" \
-H "Content-Type: application/json"
Alternatively, you can use an API key instead of a password. Replace {username}
and {api_key}
with your IBM Cloud Pak for Data credentials.
curl -k -X POST "https://{cpd_cluster_host}/icp4d-api/v1/authorize" \
-d "{\"username\":\"{username}\",\"api_key\":\"{api_key}\"}" \
-H "Content-Type: application/json"
Authenticating to the API by using an access token. Replace {token}
with your details.
curl "https://{cpd_cluster_host}/v1/{method}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json"
Authenticating to the API by using a Base64 encoded API key token. Replace {token}
with your details.
Generate the token by using an API key and its respective username.
echo "<username>:<api_key>" | base64
curl "https://{cpd_cluster_host}/v1/{method}" \
-H "Authorization: ZenApiKey {token}" \
-H "Content-Type: application/json"
Service endpoint
The service endpoint is based on your IBM Cloud Pak deployment URL.
https://{cpd_cluster_host}/usermgmt/v1/{method}
For example, if your instance is deployed at https://www.example.com:31843
, you can access the APIs at https://www.example.com:31843/usermgmt/v1/{method}
.
Example
curl -X {request_method} "https://{cpd_cluster_host}/usermgmt/v1/{method}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json"
Disabling SSL verification
All Cloud Pak for Data services use Secure Sockets Layer (SSL) (or Transport Layer Security (TLS)) for secure connections between the client and server. The connection is verified against the local certificate store to ensure authentication, integrity, and confidentiality.
If you use a self-signed certificate, you need to disable SSL verification to make a successful connection.
Enabling SSL verification is highly recommended. Disabling SSL jeopardizes the security of the connection and data. Disable SSL only if necessary, and take steps to enable SSL as soon as possible.
To disable SSL verification for a curl request, use the --insecure
(-k
) option with the request.
Example that disables SSL verification
curl -k -X {request_method} "{url}/v1/{method}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json"
Error handling
IBM Cloud Pak for Data uses standard HTTP response codes to indicate whether a method was successful. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user. Response codes are listed with the method.
Configuring monitors and alerts
You can browse generated events and configure monitors and alerts by using the Alerting APIs.
Required role: You must have administration privileges in Cloud Pak for Data. API authentication uses an authorization token with administration privileges.
Creating custom cards for the home page
You can create custom cards to display key performance indicators on the Cloud Pak® for Data home page with the Custom cards API.
Required role: You must have administration privileges in Cloud Pak for Data. API authentication uses an authorization token with administration privileges.
Cards give users access to recently used items and an overview of important changes and alerts. The list of available cards is determined by the services that are installed on the platform. You can also add custom cards to the home page with the custom cards API. You can prevent certain cards from being displayed on the home page by disabling them. Each user might see only a subset of the cards based on their permissions and the services that they have access to, so consider how disabling a card affects users with different roles.
You can start with a template to create each of the custom cards that are shown in the following image. See the template types for a description of the templates that were used.
Template types:
- The
donut
template illustrates an array of values as percentages in a donut chart. - The
bar
template creates a two-dimensional bar graph. - The
big_number
template highlights significant data. - The
text_list
displays a list of text strings. - The
number_list
displays a list of numeric values and associated text. - The
list
displays a list of navigation links. The list can contain headers and associated clickable links. - The
content_block
displays rows of text or links. Each row can be a paragraph of text or clickable links.
Managing secrets and vaults
You can safeguard credentials and secrets with access control and audit logging by using the Vaults and secrets APIs.
Required role: An authorization token is generally created for a specific user ID. That user ID determines the permissions that are applied in the API calls. For example, the API returns only the content for those secrets that are visible to the particular user ID.
Security is critical when services use secrets such as database access credentials, SSL certificates, API keys, and authentication tokens. Customers are also subject to regulatory compliance, which means that they must report and audit privileged credential usage, and forensic analysis of access. If you store and access credentials in plain text on applications and services, you might incur a serious security risk. You need tools that provide access and secrets management, both for system identities and user identities.
The Vaults and secrets APIs provide a centralized mechanism that is hardened by data encryption, secure access control, authorization checks, and auditing. You can securely store and tightly control access to secrets (such as passwords, tokens, API keys, encryption keys, and certificates) to protect access to sensitive data. You can store credentials such as passwords, API keys, tokens, certificates, or other sensitive information within a vault.
You can also manage credentials and secrets by using the user interface. For more information, see Managing secrets and vaults.
You can also access vaults by using Python in Notebooks, scripts, and other code to store and retrieve secrets. For more information, see the IBM CPD Core Python Client.
Managing persistent volume instances
You can create and manage persistent volume instances on your existing Cloud Pak® for Data storage devices with the Volumes APIs.
Required role: To use this API, you must have the Create service instances permission in Cloud Pak for Data. You can check which permissions you have from your profile.
Many enterprise applications use a mounted file system to work with data sets. For example, many Spark jobs process CSV, PARQUET, and AVRO files that are stored on a POSIX-compliant shared file system that can be accessed by all of the executors. However, you might need to store source code for Spark jobs or other packages that can be used by your Spark jobs. In some cases, these additional files need to be stored on a mountable, shared file system. You can use a volume instance to store these files by using the Volumes API.
Before you get started, review What types of storage can you use to create a storage volume?
You can perform the following tasks:
- Work directly with the files on the file system
-
You can use the managed volume instances to host files. You can give Cloud Pak for Data users access to the volume instance, and the volume instance can be accessed by services that are running on Cloud Pak for Data.
-
With the Volumes API, you can create persistent volumes without direct access to Kubernetes or in-depth knowledge of Kubernetes storage principles. However, you should have a basic understanding of Kubernetes storage concepts.
- Store and access files that are generated by other services in your ecosystem
-
The volume instance is created through a Red Hat® OpenShift® storage account in the Cloud Pak for Data project (namespace) on behalf of the users who creates the volume instance.
-
After a volume instance is created, you can associate (mount) the volume in the appropriate pods in your Cloud Pak for Data deployment.
- Enable access management for specific volumes
-
You can specify which users have access to the volume instance to ensure that only authorized users have access to the volume. Important: A user with direct access to Kubernetes and sufficient privileges on the storage device can potentially still access a volume instance that was created by using the Volumes API.
- Allow authorized users to use the Volume API to upload files into their volumes
-
Authorized users can upload, view, or delete files on the volume by using the Volumes API and its utilities.
Methods
Get authorization token
This API generates a bearer token for a user using their Cloud Pak for Data credentials.
POST /icp4d-api/v1/authorize
Request
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 configuration info
This API allows users to view configuration information for the user management environment and LDAP.
GET /usermgmt/v1/usermgmt/config
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Pass language for translated content.
Example:
en-US
Query Parameters
Set to true to return all configurations.
Default:
false
Example:
true
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/config?includeAll={includeAll}' -H 'Accept-Language: en-US' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
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: ZenApiKey {TOKEN}' -d '{ auto_signup: {auto_signup}, externalLDAPEmailField: {externalLDAPEmailField}, externalLDAPFirstNameField: {externalLDAPFirstNameField}, externalLDAPGroupField: {externalLDAPGroupField}, externalLDAPGroupMemberField: {externalLDAPGroupMemberField}, externalLDAPGroupSearchBase: {externalLDAPGroupSearchBase}, externalLDAPGroupSearchField: {externalLDAPGroupSearchField}, externalLDAPHost: {externalLDAPHost}, externalLDAPLastNameField: {externalLDAPLastNameField}, externalLDAPPort: {externalLDAPPort}, externalLDAPSearchBase: {externalLDAPSearchBase}, externalLDAPSearchField: {externalLDAPSearchField}, externalLDAPSearchPassword: {externalLDAPSearchPassword}, externalLDAPSearchUser: {externalLDAPSearchUser}, externalLDAPPrefix: {externalLDAPPrefix}, externalLDAPSuffix: {externalLDAPSuffix} }'
Response
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Form Parameters
Automatically approve users who request access, without explicit admin approval.
Email field in a user entry.
Example:
mail
First name field in a user entry.
Example:
givenName
Group field in a user entry.
Example:
memberOf
Member field in a LDAP group entry.
Example:
member
Point in the LDAP tree where groups are searched from.
Example:
dc=wdp,dc=com
LDAP field used for Group search criteria.
Example:
cn
The LDAP server's host.
Example:
ldap://<host>
Last name field in a user entry.
Example:
sn
The LDAP server's port.
Example:
389
The LDAP server's prefix.
The LDAP server's search base.
Example:
dc=wdp,dc=com
The LDAP server's search field.
Example:
mail
The LDAP server's search user.
Example:
search.user@wdp.com
The password for login in clear text.
Example:
password
The user name for login.
Example:
username
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/preauth/validateConfig' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: ZenApiKey {TOKEN}' --data-urlencode 'externalLDAPHost{externalLDAPHost}=' --data-urlencode 'externalLDAPPort{externalLDAPPort}=' --data-urlencode 'username{username}=' --data-urlencode 'password{password}=' --data-urlencode 'externalLDAPMechanism{externalLDAPMechanism}=' --data-urlencode 'externalLDAPPrefix={externalLDAPPrefix}' --data-urlencode 'externalLDAPSuffix={externalLDAPSuffix}' --data-urlencode 'externalLDAPSearchUser={externalLDAPSearchUser}' --data-urlencode 'externalLDAPSearchPassword{externalLDAPSearchPassword}=' --data-urlencode 'externalLDAPSearchBase={externalLDAPSearchBase}' --data-urlencode 'externalLDAPSearchField{externalLDAPSearchField}=' --data-urlencode 'externalLDAPGroupField{externalLDAPGroupField}='
Get users
This API allows users to view and filter a list of user details on the platform.
Details include user info, groups, roles, and permissions related to the user.
GET /usermgmt/v1/usermgmt/users
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Set to true to return all users including users in pending/denied access states.
Example:
true
Specify search string for pattern matching.
Example:
example
Comma-separated string. Return list of users with one of the permissions.
Example:
manage_vaults_and_secrets,share_secrets
Comma-separated string. Return list of users with one of the roles.
Example:
administrator_role,custom_user_role
Comma-separated string. Return list of users with one of the roles assigned individually or through User-Groups.
Example:
api_admin,api_developer
Flag to retrieve users that do not belong to mentioned user_roles.
Example:
true
Flag to retrieve users having at least one role assigned.
Example:
true
Flag to retrieve users having no roles assigned.
Example:
true
Comma-separated string. Return list of group_ids.
Example:
10000,10001
Flag to retrieve users that do not belong to mentioned user_groups.
Example:
true
Flag to retrieve count of all Cloud Pak for Data users.
Example:
true
Offset required for pagination.
Max number of records to return in a page.
Example:
25
Sort user records based on a specific column.
Allowable values: [
uid
,username
,displayName
,email
,created_timestamp
]Example:
created_timestamp
Sorting order either ascending or descending.
Allowable values: [
ASC
,DESC
]Default:
DESC
Example:
DESC
Set to true to return groups for each user.
Default:
true
Example:
true
Set to true to return profile icon for each user.
Default:
false
Example:
true
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/users?includeAll={includeAll}&search_str={search_str}&permissions={permissions}&user_roles={user_roles}&roles={roles}&negate_user_roles={negate_user_roles}&any_role={any_role}&no_roles={no_roles}&user_groups={user_groups}&negate_user_groups={negate_user_groups}&include_users_count={include_users_count}&offset={offset}&limit={limit}&sort_by={sort_by}&sort_order={sort_order}&include_groups={include_groups}&include_profile_picture={include_profile_picture}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
The user name.
Example:
example
The authenticator for the user.
Possible values: [
default
,external
]Example:
external
The date and time that the user account was created.
Example:
1655162210393
The current status of the user's account.
Possible values: [
locked
,enabled
,disabled
]Example:
enabled
Indicate whether user is deletable.
Example:
true
The name that is displayed for this user.
Example:
example
The user's unique email address.
Example:
example@ibm.com
- Examples:View
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:View
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:
Admin
The unique identifier for the user.
Example:
1000331015
The roles assigned to the user.
Examples:ViewCollection of trivial miscellaneous user attributes.
Examples:View
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Query for user profile by given user ID.
Example:
1000331015
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/usermgmt/user/{uid}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
The user name.
Example:
example
The authenticator for the user.
Possible values: [
default
,external
]Example:
external
The date and time that the user account was created.
Example:
1655162210393
The current status of the user's account.
Possible values: [
locked
,enabled
,disabled
]Example:
enabled
Indicate whether user is deletable.
Example:
true
The name that is displayed for this user.
Example:
example
The user's unique email address.
Example:
example@ibm.com
- Examples:View
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:View
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:
Admin
The unique identifier for the user.
Example:
1000331015
The roles assigned to the user.
Examples:ViewCollection of trivial miscellaneous user attributes.
Examples:View
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Set to true when this endpoint is used for migration purposes.
The user name.
Example:
example
The authenticator for the user.
Allowable values: [
default
,external
]Example:
external
The date and time that the user account was created.
Example:
1655162210393
The current status of the user's account.
Allowable values: [
locked
,enabled
,disabled
]Example:
enabled
Indicate whether user is deletable.
Example:
true
The name that is displayed for this user.
Example:
example
The user's unique email address.
Example:
example@ibm.com
- Examples:View
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:View
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:
Admin
The unique identifier for the user.
Example:
1000331015
The roles assigned to the user.
Examples:ViewCollection of trivial miscellaneous user attributes.
Examples:View
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "displayName":{displayName}, "email":{email}, "username":{username}, "password":{password}, "user_roles":{user_roles} }'
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "username":{username}, "displayName":{displayName}, "email":{email}, "authenticator":{authenticator}, "user_roles":{user_roles}, "misc": { "realm_name":{realm_name}, "extAttributes":{extAttributes} } }'
Response
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Comma-separated string of user IDs.
Example:
1,2
Flag to send numbers of users in response.
Example:
true
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/users?uids={uids}&count_only={count_only}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
The user name.
Example:
example
The authenticator for the user.
Possible values: [
default
,external
]Example:
external
The date and time that the user account was created.
Example:
1655162210393
The current status of the user's account.
Possible values: [
locked
,enabled
,disabled
]Example:
enabled
Indicate whether user is deletable.
Example:
true
The name that is displayed for this user.
Example:
example
The user's unique email address.
Example:
example@ibm.com
- Examples:View
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:View
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:
Admin
The unique identifier for the user.
Example:
1000331015
The roles assigned to the user.
Examples:ViewCollection of trivial miscellaneous user attributes.
Examples:View
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. Any user who has the email address that is already in use will not get access granted.
POST /usermgmt/v1/user/bulk
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
List of user objects.
The user name.
Example:
example
The authenticator for the user.
Allowable values: [
default
,external
]Example:
external
The date and time that the user account was created.
Example:
1655162210393
The current status of the user's account.
Allowable values: [
locked
,enabled
,disabled
]Example:
enabled
Indicate whether user is deletable.
Example:
true
The name that is displayed for this user.
Example:
example
The user's unique email address.
Example:
example@ibm.com
- Examples:View
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:View
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:
Admin
The unique identifier for the user.
Example:
1000331015
The roles assigned to the user.
Examples:ViewCollection of trivial miscellaneous user attributes.
Examples:View
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/bulk' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '[ { "displayName":{displayName}, "email":{email}, "username":{username}, "password":{password}, "user_roles":{user_roles} } ]'
Response
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/user/currentUserInfo' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
The user name.
Example:
example
The authenticator for the user.
Possible values: [
default
,external
]Example:
external
The date and time that the user account was created.
Example:
1655162210393
The current status of the user's account.
Possible values: [
locked
,enabled
,disabled
]Example:
enabled
Indicate whether user is deletable.
Example:
true
The name that is displayed for this user.
Example:
example
The user's unique email address.
Example:
example@ibm.com
- Examples:View
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:View
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:
Admin
The unique identifier for the user.
Example:
1000331015
The roles assigned to the user.
Examples:ViewCollection of trivial miscellaneous user attributes.
Examples:View
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
The user name.
Example:
example
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/user/{username}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
The user name.
Example:
example
The authenticator for the user.
Possible values: [
default
,external
]Example:
external
The date and time that the user account was created.
Example:
1655162210393
The current status of the user's account.
Possible values: [
locked
,enabled
,disabled
]Example:
enabled
Indicate whether user is deletable.
Example:
true
The name that is displayed for this user.
Example:
example
The user's unique email address.
Example:
example@ibm.com
- Examples:View
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:View
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:
Admin
The unique identifier for the user.
Example:
1000331015
The roles assigned to the user.
Examples:ViewCollection of trivial miscellaneous user attributes.
Examples:View
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Name of the user to update.
Example:
example
Query Parameters
If
true
, roles are added to current roles. Otherwise, roles are overwritten.Default:
false
Example:
true
Updated user object.
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: ZenApiKey {TOKEN}' -d '{ "displayName":{displayName}, "email":{email}, "username":{username}, "user_roles":{user_roles} }'
Response
UID of the updated user.
Example:
1000331015
Example:
success
Example:
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Name of the user to delete.
Example:
example
curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v1/user/{username}' -H 'Authorization: ZenApiKey {TOKEN}'
Response
UID of the updated user.
Example:
1000331015
Example:
success
Example:
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 token and session cookie.
POST /usermgmt/v1/user/renewToken
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Token expiry time.
Example:
12
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/renewToken?expiry_time={expiry_time}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Successful renew token response body.
Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Example:
<csrf_token>
Example:
success
Example:
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/user/apiKey' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Successful API key response body.
Example:
<api_key>
Example:
success
Example:
success
Status Code
Success.
Bad Request.
Unauthorized.
Could not find the user associated with the 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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Form Parameters
The new password.
Example:
newPassword
The current password.
Example:
currentPassword
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/changemypassword' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: ZenApiKey {TOKEN}' --data-urlencode 'password={password},' --data-urlencode 'currentPassword={currentPassword}' curl -k -X POST
Change a user's password
This API allows users with an administrator role to change a user's password.
This cannot be done for a user authenticated via LDAP/SAML/IAM.
POST /usermgmt/v1/user/changeuserpassword
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Form Parameters
The user name.
Example:
username
The new password.
Example:
newPassword
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/user/changeuserpassword' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: ZenApiKey {TOKEN}' --data-urlencode 'username={username}' --data-urlencode 'password={password}'
Update current user profile
This API allows the current logged in user to update their user profile.
PUT /usermgmt/v2/own_profile
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Flag to set theme for user profile.
Example:
true
curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v2/own_profile?dark_mode={dark_mode}' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Successful setOwnProfile response body.
UID of the updated user.
Example:
1000331015
Example:
success
Example:
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Comma-separated string of group identifiers.
Example:
10000,10001
Comma-separated string of role identifiers.
Example:
administrator,api_user
Set to true to include details about users in this group.
Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/groups?group_identifiers={group_identifiers}&role_identifiers={role_identifiers}&include_members={include_members}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
List of user groups.
Unique ID indentifying the User-Group.
Example:
10000
Name of the user group.
Example:
All users
More detailed information about the user group.
Example:
All users are implicitly part of this group.
Creation datetime.
Example:
2022-05-25T22:03:31.193Z
User who created the User-Group.
Example:
admin
Last updated datetime.
Example:
2022-05-25T22:03:31.193Z
Collection of miscellaneous group attributes.
Examples:ViewStringified number of users in the group
Example:
42
Permissions associated with the group.
Examples:View
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Name of the user group.
Example:
example group
More 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:View
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/groups' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "name": {name}, "description": {description}, "account_id": {account_id}, "role_identifiers": {role_identifiers} }'
Response
Example:
2022-06-20T18:21:21.763Z
Example:
admin
Example:
This is a user group description.
Example:
10001
Example:
Created
Example:
example group
Example:
2022-06-20T18:21:21.763Z
Example:
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Unique ID indentifying the User-Group.
Example:
10001
Name of the user group.
Example:
example group
More 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:View
- Examples:View
curl -k -X PATCH 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "name": {name}, "description": {description}, "account_id": {account_id}, "add_role_identifiers": {add_role_identifiers}, "remove_role_identifiers": {remove_role_identifiers} }'
Response
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Conflict.
Internal Server Error.
{ "group_id": 10001, "message": "success", "_messageCode_": "success" }
{ "_messageCode_": "bad_request", "message": "Payload is invalid", "_statusCode_": 400, "exception": "Request contains invalid role identifiers." }
{ "_messageCode_": "authorization_fail", "message": "Not authorized. This action may require additional privileges or the administrator permission", "_statusCode_": 401 }
{ "_messageCode_": "conflict_error", "message": "Request conflicts with the current state of the server", "_statusCode_": 409, "exception": "Another usergroup with the same name exists." }
{ "_messageCode_": "internal_error", "message": "Internal server error", "_statusCode_": 500, "exception": "duplicate key value violates unique constraint \"user_group_roles_group_id_role_id_key\"" }
Delete user group
This API allows users with an administrator role to delete a user group.
DELETE /usermgmt/v2/groups/{group_id}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Unique ID indentifying the User-Group.
Example:
10001
curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Status Code
Created.
Unauthorized.
Not Found.
Internal Server Error.
{ "group_id": 10001, "message": "success", "_messageCode_": "success" }
{ "_messageCode_": "authorization_fail", "message": "Not authorized. This action may require additional privileges or the administrator permission", "_statusCode_": 401 }
{ "_messageCode_": "not_found", "message": "The asset is not found", "_statusCode_": 404, "exception": "User-Group not found" }
Get group members
This API allows users to view details about users associated with a certain group.
GET /usermgmt/v2/groups/{group_id}/members
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
User-Group identifier
Example:
10001
Query Parameters
True
ifuser_details
are required in response.Default:
false
Offset required for pagination.
Max number of records to return in a page.
Example:
25
Sorting the user records based upon specific column.
Allowable values: [
uid
,username
,displayName
,email
]Default:
uid
Example:
uid
Sorting order either ascending or descending.
Allowable values: [
ASC
,DESC
]Default:
DESC
Example:
DESC
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/members?include_user_details={include_user_details}&offset={offset}&limit={limit}&sort_by={uid}&sort_order={sort_order}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Successful GET group members response body.
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}/members
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
User-Group identifier.
Example:
10001
Payload containing LDAP groups and/or UIDs.
List of LDAP distinguished names to be added to the group.
Examples:ViewList of groups coming from the IAM's IDP.
Example:
[]
List of UIDs to be added to the group.
Examples:ViewThe necessary object to construct the rules based on user attributes.
Allowable values: [
and
,or
]Example:
and
The attribute-based rule object.
Examples:View
attribute_rules
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/members' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "ldap_groups": {ldap_groups}, "user_identifiers": {user_identifiers}, "attribute_rules": {attribute_rules} }'
Response
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
{ "group_id": 10001, "message": "success", "_messageCode_": "success" }
{ "_messageCode_": "bad_request", "message": "Payload is invalid", "_statusCode_": 400, "exception": "Request validation failed: Parameter (group_id) is not a valid number: notAGroupId" }
{ "exception": "User-Group not found", "_messageCode_": "not_found", "message": "The asset is not found", "_statusCode_": 404 }
Delete group member
This API allows users with an administrator role to delete a user from a user group.
DELETE /usermgmt/v2/groups/{group_id}/members/{uid}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
User-Group identifier.
Example:
10001
The user's unique identifier.
Example:
1000331015
curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/members/{uid}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Status Code
Success.
Unauthorized.
Not Found.
Internal Server Error.
{ "group_id": 10001, "user_id": 1000331015, "message": "success", "_messageCode_": "success" }
{ "_messageCode_": "member_undeletable", "message": "No members based on the provided criteria can be removed.", "_statusCode_": 404, "exception": "member_undeletable" }
Get group membership rules
This API allows users to view membership rule details for a group.
Membership rules define who can be a member of a group.
For example, the group membership rule 'uid=1000330999' states that the user with UID 1000330999 is a member of that group.
Similarly, the rule 'ldapGroup="CN=marketing,DC=ibm,DC=com"' states that all users in the LDAP group with that distinguished name (DN) are members of this group.
GET /usermgmt/v2/groups/{group_id}/membership_rules
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
User-Group identifier.
Example:
10001
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/groups/{group_id}/membership_rules' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
The attribute-based rule object.
results
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Rule identifier.
Example:
123
Payload containing group membership rules.
The necessary object to construct membership rules based on user attributes.
Allowable values: [
and
,or
]The attribute-based rule object.
attribute_rules
curl -k -X PUT 'https://{cpd_cluster_host}/usermgmt/v2/groups/membership_rules/{rule_id}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "realm_name": {realm_name}, "logical_operator": {logical_operator}, "rules": {rules} }'
Response
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
{ "message": "success", "rule_id": 123, "_messageCode": "success" }
{ "exception": "Request validation failed: Parameter (body) failed schema validation", "_messageCode_": "bad_request", "message": "Payload is invalid", "_statusCode_": 400 }
Delete membership rule
This API allows a user with an administrator role to delete a membership rule via its ID.
DELETE /usermgmt/v2/groups/membership_rules/{rule_id}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Rule identifier.
Example:
123
curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v2/groups/membership_rules/{rule_id}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
{ "rule_id": 123, "_messageCode_": "success", "message": "success" }
{ "exception": "Request validation failed: Parameter (rule_id) is not a valid number: notARuleId", "_messageCode_": "bad_request", "message": "Payload is invalid", "_statusCode_": 400 }
{ "exception": "Membership Rule could not be found", "_messageCode_": "not_found", "message": "The asset is not found", "_statusCode_": 404 }
Get LDAP users
This API allows users to view and filter a list of LDAP users.
POST /usermgmt/v2/ldap/users
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
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: ZenApiKey {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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
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: ZenApiKey {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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Pass language for translated content.
Example:
en-US
Query Parameters
Set to true to return count of users assigned to each role.
Default:
false
Set to true to return count of platform users assigned to each role individually.
Default:
false
Set to true to return count of user-groups assigned to each role.
Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v1/roles?include_users_count={include_users_count}&include_platform_users_count={include_platform_users_count}&include_user_groups_count={include_user_groups_count}' -H 'Accept-Language: en-US' -H 'Authorization: ZenApiKey {TOKEN}'
Response
doc
rows
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Create role object.
curl -k -X POST 'https://{cpd_cluster_host}/usermgmt/v1/role' -H 'Authorization: ZenApiKey {TOKEN}' -H 'Content-Type: application/json' -d '{ "description": {description}, "permissions": {permissions} }'
Response
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Extension name of the role that needs to be updated.
Example:
22c69856-3e21-4301-b83c-3b226e957d9e
Update role object.
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: ZenApiKey {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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Pass language for translated content.
Example:
en-US
Path Parameters
Extension name of the role that needs to be deleted.
Example:
22c69856-3e21-4301-b83c-3b226e957d9e
curl -k -X DELETE 'https://{cpd_cluster_host}/usermgmt/v1/role/{id}' -H 'Accept-Language: en-US' -H 'Authorization: ZenApiKey {TOKEN}'
Response
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
curl -k -X GET 'https://{cpd_cluster_host}/usermgmt/v2/attributes' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Example:
Location
Example:
simple
Example:
string
Example:
true
Example:
location
other property
usermgmt_default
data
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" }
Give access to an instance for one or more users
Gives one or more users access to an instance. By default, only the user who created the instance is an administrator. You must include the instance ID as a JSON string in the HTTP request body. You can get the instance ID by using /zen-data/v3/service_instances.
POST /zen-data/v2/serviceInstance/users
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Form Parameters
users
groups
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/serviceInstance/users' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "serviceInstanceID":"<volume-instance-ID>", "users":[ { "display_name":"<display-name-of-user>", "role":"<access-level>", "uid":"<uid-of-user>", "username":"<username-of-user>" } ] }'
Revoke access to an instance
Revokes a user's access to the specified instance. You must include the instance ID as a JSON string in the HTTP request body. You can get the instance ID by using /zen-data/v3/service_instances.
DELETE /zen-data/v2/serviceInstance/users
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <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}/zen-data/v2/serviceInstance/users' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "serviceInstanceID":"<volume-instance-ID>", "users":[ "<uid-of-user>" ] }'
Get a list of users with access to an instance
Retrieves the list of users who have access to the specified instance. The role of each user is also returned.
GET /zen-data/v2/serviceInstance/users
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Service Instance ID of the service.
Include profile picture or not.
Default:
false
Roles to query.
Includes group users or not.
Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/serviceInstance/users?sID=<volume_instance_id>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Change a user's role on an instance
Changes the user's role (access level) on the specified instance. You must include the instance ID as a JSON string in the HTTP request body. You can get the instance ID by using /zen-data/v3/service_instances. Note: Can be used only by the administrator of the service instance
PATCH /zen-data/v2/serviceInstance/users/role
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
ServiceInstance metadata artifact that must be added to the database.
curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/v2/serviceInstance/users/role' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "serviceInstanceID":"<volume-instance-ID>", "roles":[ { "uid":"<uid-of-user>", "newRole":"<new-access-level>" } ] }'
Create a service instance
Creates a service instance. You must include the service instance definition as a JSON string in the HTTP request body. Can be initiated only by a user with the Create service instances permission.
POST /zen-data/v3/service_instances
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
ServiceInstance metadata artifact that must be added to the database.
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_name
is 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:
false
This object will be forwarded to service provider without saving to database.
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "addon_type": "volumes", "addon_version": "-", "create_arguments": { "metadata": { "volume_type": "NEW_PVC", "storageClass": "nfs-client", "storageSize": "1Gi", "mount_path": "<mount-path>" } }, "namespace": "zen", "display_name": "volumes-sample-1" }'
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "addon_type": "volumes", "addon_version": "-", "create_arguments": { "metadata": { "volume-type": "EXISTING_PVC", "existing_pvc_name": "user-home-pvc", "supplemental_groups": [8888, 1111] "mount_path": "<mount-path>" } }, "namespace": "zen", "display_name": "existing-pv-sample-1" }'
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "addon_type": "volumes", "addon_version": "-", "create_arguments": { "metadata": { "volume_type": "EXTERNAL_NFS", "nfs_server_address": "9.30.10.10", "nfs_export_path": "/mnt/nfs_shares/", "mount_path": "/mnts/data/" "supplemental_groups": [8888, 1111] } }, "namespace": "<control-plane-namespace>", "display_name": "<display-name>" }'
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "addon_type": "volumes", "addon_version": "-", "create_arguments": { "metadata": { "volume_type": "SMB_CIFS", "cifs_server_address": "9.30.94.140", "cifs_export_path": "private", "mount_path": "/mnts/samba", "cifs_username": "admin" } }, "namespace": "zen", "display_name": "samba-doc-test", "transient_fields": { "cifs_password": "password" } }'
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "addon_type": "volumes", "addon_version": "-", "create_arguments": { "metadata": { "storageClass": "<storage-class>", "storageSize": "<space-allocated-to-volume>", "file_server": { "start": true, "resources": { "limits": { "cpu": "<cpu-limits>", "memory": "<memory-limits>" }, "requests": { "cpu": "<cpu-requests>", "memory": "<memory-requests>" } } } } }, "namespace": "<control-plane-namespace>", "display_name": "<display-name>" }'
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "addon_type": "ez-addon-app", "addon_version": "1.0.0.0", "create_arguments": { "description": "string", "metadata": { "NGINX_TIMEOUT": "10" }, "parameters": {} }, "display_name": "<display-name>", "pre_existing_owner": false, "transient_fields": {} }'
Get a service instance collection
Retrieves the list of service instances that you have access to.
This method no longer returns the total user count for the instance collection when the exclude_user_count query parameter is set to true.
The total user count is still returned as the default behavior for compatibility with an earlier version. However, use the new exclude_user_count parameter if you don’t require the total user count information. When you have many service instances, the response time is faster when you use the exclude_user_count parameter.
GET /zen-data/v3/service_instances
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Query Parameters
If set to true returns all service instances. This parameter can be used by an Administrator only.
Type of the add-on.
Exclude addon type volumes in the collection.
Default:
false
Version of the add-on, this parameter must be used with the
addon_type
parameter.Name of the instance to query.
Category of the add-on, this cannot be used with other parameters.
The number of service instances to skip before starting to collect the result set.
The number of service instances to return.
Example:
20
If set to true, computation of the total number of users that were added to a service instance will be skipped for all instances and omitted from the response.
Default:
false
# Retrieve service instances curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v3/service_instances' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' # Retrieve service instances with addon_type=volumes curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v3/service_instances?addon_type=volumes' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Offset of the first instance in the result list, given the order of the collection. If the offset is not specified the default is 0.
Limit of the number of instances returned. If the limit is not specified in the request, the default is 20.
Total number of instances returned.
Service instance collection
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.
Information about the data plane that is associated with the service instance if it is deployed in a remote physical location.
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.
service_instances
Status Code
Success.
Bad Request.
Unauthorized.
Not Found.
Internal Server Error.
No Sample Response
Get service instance details
Returns the details of the service instance. By default, this method returns the total user count in the return object in the "total_users": n response.
This method also returns a specific instance record with the service status if include_service_status is set to true.
This method fetches the status of the instance from the database only. It returns the live status if the status is not present in the status table, if the status expired (10 minutes), if the call failed, or if the status is unknown.
GET /zen-data/v3/service_instances/{instance_id}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Language that the add-on placeholder strings such as short and long description will be returned in.
Default:
en
Path Parameters
service instance identifier
Query Parameters
If true service status is retrieved from the provider.
Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v3/service_instances/{instance_id}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Delete a service instance
Deletes a service instance and removes users' access to the service instance. Important: The data inside the volume is not deleted and services can continue to use the volume until a Red Hat OpenShift project administrator removes the persistent volume claim to reclaim the storage. The reclaim policy that is specified in the storage class determines what happens when the persistent volume claim is deleted.
DELETE /zen-data/v3/service_instances/{instance_id}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
Service Instance Identifier
Query Parameters
Set to true if the instance must be force deleted and bypass the default defensive checks pertaining to the service status.
curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v3/service_instances/{instance_id}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Get the status of service instances
Returns the status of service instances. Service instances are ordered by created_at date, most recent to oldest.
This method fetches the status of the instances from the database cache only.
By default, this method returns the status of service instances that the user has access to.
If the bulk parameter is set to true, this method retrieves the status of service instances for the specified list of service instances, which are provided by the instance_ids parameter.
GET /zen-data/v3/service_instances/statuses
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Query Parameters
If false, returns the status of service instances that the user has access to. If true, requires the instance_ids parameter to retrieve the status of the specified service instances.
Default:
false
To specify service IDs to retrieve the status for, set the bulk parameter to true and provide a comma-separated list of service instance IDs. You can provide a maximum of 20 service instance IDs.
Include the total count of instances that the user has access to. If not set to true, the total_count field is omitted from the response.
Default:
false
The number of service instances to skip, given the order of the service instances. Service instances are ordered by created_at date, most recent to oldest. If not specified, default is 0.
Default:
0
The number of service instances to return.
Default:
20
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v3/service_instances/statuses' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
The number of services instances to be queried. If not specified, 20 service instances are returned.
The number of service instances to skip, given the order of the service instances. Service instances are ordered by created_at date, most recent to oldest. If not specified, default is 0.
The statuses for the service instances.
Total number of instances that the user has access to.
Status Code
Success.
Bad Request.
Unauthorized.
Forbidden.
Not Found.
Internal Server Error.
No Sample Response
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Number of days to retain.
Default:
3
curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/events/prune?retention_time={retention_time}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Delete metrics records
Deletes metrics records that are older than the specified number of days.
POST /zen-watchdog/v3/metrics/prune
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Number of days to retain.
Default:
30
curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v3/metrics/prune?retention_time={retention_time}' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Configure email recipients
Configures alerts to be sent as email. You can configure a connection to your SMTP server in Administration > Platform configuration.
PATCH /zen-watchdog/v1/monitoring/config/smtp
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
SMTP config for alert monitoring.
curl -k -X PATCH 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/smtp' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ “registered_emails” : [{registered_emails}] }'
View alerted events
Returns a list of events by monitor that have promoted alerts and are currently in the snooze period, which can be further filtered by a specific event type.
GET /zen-watchdog/v1/monitoring/getAlertedEvents
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
The name of the monitor. The default monitor is diagnostics.
Event type, which is used along with the
monitor_type
. The following event types are delivered with Cloud Pak for Data:check-pvc-status
(records a critical event if a PVC is unbound),check-replica-status
(records a critical event if aStatefulSet
or deployment has unavailable replicas),check-resource-status
(records a warning event if a service has reached the threshold and a critical event if it has exceeded the quota).
curl -k -X GET 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/getAlertedEvents' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Configure event type
Allows you to edit configuration details for a particular event type for a monitor.
PATCH /zen-watchdog/v1/monitoring/config/eventType
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
The name of the monitor. The default monitor is
diagnostics
.Event type. The following event types are delivered with Cloud Pak for Data:
check-pvc-status
(records a critical event if a PVC is unbound),check-replica-status
(records a critical event if aStatefulSet
or deployment has unavailable replicas),check-resource-status
(records a warning event if a service has reached the threshold and a critical event if it has exceeded the quota).
Event config.
curl -k -X PATCH 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/eventType' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ <body_params> }'
Configure alert rules
Configures rules for critical and warning events, including the snooze period and whether an alert is needed when an incident corrects itself.
PATCH /zen-watchdog/v1/monitoring/config/alertType
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Name of the alert type. The default
alert_type
is platform.The severity for which the rules need to be updated. One of the following options:
critcal
,warning
. You can't configure the alert rules for informational alerts.Allowable values: [
critical
,warning
]Event type.
Event config.
Determines how to trigger alerts. One of the following options:
immediate
,custom
. Custom needsalert_count
andalert_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: ZenApiKey {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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Form Parameters
The SNMP server host address.
The community string associated with the SNMP connection.
The SNMP server port.
curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/snmp' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
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: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Form Parameters
The URL of the webhook to post to a Slack channel.
curl -k -X POST 'https://{cpd_cluster_host}/zen-watchdog/v1/monitoring/config/slack' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Get a list of monitors, profiles, or alert types
Lists all registered monitors and associated event types. The default monitor is diagnostics. Lists all alert types or rules, which define when alerts need to send. The default alert type is platform. Lists all registered alert profiles to enable or disable a certain type of alert (SMTP, SNMP, or Slack). Also provides metadata for the alert methods, including the list of email addresses that are registered to receive alerts.
GET /zen-data/v1/extensions
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Pass language for translated content.
Example:
en-US
Query Parameters
Set to
zen_alert_monitor
to get a list of monitors. Set tozen_alert_type
to get a list of alert types.Identifier of a particular extension.
Array of particular extensions' names.
Type of preference.
Allowable values: [
global
,user
]Default:
user
Identifier for a particular source.
Query parameter when disabled will return the disabled extensions.
Default:
enabled
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/extensions?extension_point_id=zen_alert_monitor' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/extensions?extension_point_id=zen_alert_type' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/extensions?extension_point_id=zen_alert_profile' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Get a list of custom cards
Retrieves the properties for the custom cards that you can update.
GET /zen-data/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 /zen-data/v1/custom_cards/{key}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
The name of the card that you want to create or replace. The string must be unique. If a custom card with the specified key does not exist, the custom card is created, otherwise the existing custom card is replaced.
Update role object.
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:
1
The display name for the card. The string must be 40 characters or less.
Example:
Disk usage
Defines the display type of the card. The
template_type
parameter must be one of the following:bar
,big_number
,content_block
,donut
,list
,number_list
,text_list
).Example:
big_number
An 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 deposits
Identifiers that can be defined by the services for use in their UI components.
Example:
566c3a42-610c-48e8-a879-9b175b7a52cc
Specifies 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.bar
The interval in seconds at which the content is refreshed by the source.
Default:
0
Example:
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: ZenApiKey {TOKEN}' -d '{ "permissions": ["manage_catalog"], "order": 1, "title": "Disk usage", "template_type": "big_number", "data": { "big_number_data": { "metric": "55", "sub_text": "Increase since last month", "prefix": "ArrowUp32", "suffix": "%", "footer_1": "867 Total vulnerabilities", "footer_2": "AskPQL 2.3 package most at risk" } } }'
Response
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 /zen-data/v1/custom_cards/{key}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
The name of the card that you want to update.
Update role object.
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:
2
The display name for the card. The string must be 40 characters or less.
Example:
Disk usage
Defines the display type of the card. The
template_type
parameter must be one of the following:bar
,big_number
,content_block
,donut
,list
,number_list
,text_list
).Example:
donut
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.
identifiers that can be defined by the services for use in their UI components.
Example:
566c3a42-610c-48e8-a879-9b175b7a52cc
Specifies 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.bar
The interval in seconds at which the content is refreshed by the source.
Default:
0
Example:
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: ZenApiKey {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 } }
Delete a custom card
Deletes an existing card with the specified key.
DELETE /zen-data/v1/custom_cards/{key}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
The name of the custom card that you want to delete.
curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v1/custom_cards/os_vulnerabilities' -H 'Accept-Language: en-US' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Store an external vault configuration
Creates an external vault integration by using this API.
POST /zen-data/v2/vaults
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Query Parameters
Validate vault connection.
Default:
false
Validate vault connection and save.
Default:
false
Sensitive payload to be secured.
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_cert
orhashicorp_token
.A short description for your vault.
The object to hold test secret reference information. If the query parameter
vaildate=true
is 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: ZenApiKey {TOKEN}' -d '{ "description": "This is cyberark aam vault", "details": { "vault_address": "https://vault.myorg.com:14506", "app_id": "testappid", "client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQprZXkKLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0K", "client_certificate" : "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCmNlcnQKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQoK" }, "type": "cyberark_aam_cert", "vault_name": "My-cyberarkaam-vault" }'
Retrieve details about external vault integrations
Retrieves details about external vault integrations for user.
GET /zen-data/v2/vaults
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Query Parameters
The number of vaults to skip before starting to collect the result set.
Default:
0
The number of vaults to return.
Default:
50
Preview secrets.
Default:
false
Sort by the field (such as sort=display_name or sort=-display_name for descending). The supported sort columns are:
vault_name
,owned_by
,created_by
,uploaded_at
,total_secrets
.Comma-separated provider names (such as CyberArk AAM, HashiCorp).
A name for your vault. This name must be unique across all the vaults that you own and that are currently stored in the vault.
Match on all or any criteria, possible values.
Allowable values: [
any
,all
]Default:
any
If
true
, returns all vaults when user has manage vaults permission.Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/vaults?limit=2&sort=updated_at&provider_name=cyber,hashi' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Offset of the first vault in the result list. If the offset is not specified in the request, the default is 0.
Limit of the number of vaults returned. If the limit is not specified in the request, the default is 20.
Total number of vaults returned.
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 /zen-data/v2/vaults/{vault_urn}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
The vault identifier. This parameter uses a specific notation:
<creator uid>:<vault_name>
.
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/vaults/<vault_urn>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Update external vault configuration
Updates configuration details of an external vault, response does not includes sensitive data.
PATCH /zen-data/v2/vaults/{vault_urn}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
The vault identifier. This parameter uses a specific notation:
<creator uid>:<vault_name>
.
Query Parameters
Validate vault connection.
Default:
false
Validate vault connection and save.
Default:
false
Sensitive payload to be secured.
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=true
is 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: ZenApiKey {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 /zen-data/v2/vaults/{vault_urn}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
The vault identifier. This parameter uses a specific notation:
<creator uid>:<vault_name>
.
curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v2/vaults/<vault_urn>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Initiate the transfer of ownership of a vault
Initiates the transfer of ownership of a vault and any secrets in the vault to a different owner.
POST /zen-data/v2/vaults/{vault_urn}/transfers
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
The vault identifier. This parameter uses a specific notation:
<creator uid>:<vault_name>
.
Query Parameters
If
true
, transfer re-submission will be executed only if allowed transfer duration is over.Default:
false
Sensitive payload to be secured.
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: ZenApiKey {TOKEN}' -d '{ new_owner_uid": "1000331007" }'
Response
Status Code
Success.
Transfer vault request accepted.
Bad Request.
Unauthorized.
Forbidden.
Not Found.
Conflict.
Internal Server Error.
{ "value": { "metadata": { "created_at": "2022-02-24T21:36:45.677Z", "created_by": "user4", "description": "Create HashiCorp vault for transferring vault ownership tests synchronously.", "invalid_auth": true, "invalid_owner": false, "owned_by": "user7", "owner_uid": 1000331007, "provider_name": "Hashicorp", "secret_preview": "vault-hashi-uc-trans-vault-secret-1vault-hashi-uc-trans-vault-secret-2vault-hashi-uc-trans-vault-secret-3", "total_secrets": 3, "updated_at": "2022-02-24T21:36:45.677Z", "vault_name": "vault-hashi-uc-trans-vault", "vault_type": "hashicorp_token", "vault_urn": "1000331031:vault-hashi-uc-trans-vault" } } }
Transfer vault to user
Authenticates the external vault and transfers it to the new owner.
PATCH /zen-data/v2/vaults/{vault_urn}/transfers
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
The vault identifier. This parameter uses a specific notation:
<creator uid>:<vault_name>
.
Sensitive payload to be secured.
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=true
is 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: ZenApiKey {TOKEN}' -d '{ "vault_address": "<vault-address>", "access_token": "<token>" }'
Response
Status Code
Success.
Success.
Bad Request.
Unauthorized.
Forbidden.
Not Found.
Conflict.
Internal Server Error.
{ "value": { "metadata": { "created_at": "2022-02-24T21:36:45.677Z", "created_by": "user4", "description": "create hashicorp vault for transferring vault ownership tests synchronously", "invalid_auth": true, "invalid_owner": false, "owned_by": "user7", "owner_uid": 1000331007, "provider_name": "Hashicorp", "secret_preview": "vault-hashi-uc-trans-vault-secret-1vault-hashi-uc-trans-vault-secret-2vault-hashi-uc-trans-vault-secret-3", "total_secrets": 3, "updated_at": "2022-02-24T21:36:45.677Z", "vault_name": "vault-hashi-uc-trans-vault", "vault_type": "hashicorp_token", "vault_urn": "1000331031:vault-hashi-uc-trans-vault" } } }
Store secret or reference
Stores and secures a secret or secret reference to an external vault in an internal vault.
POST /zen-data/v2/secrets
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Query Parameters
Validate secret reference.
Default:
false
Validate secret reference and save.
Default:
false
Sensitive payload to be secured.
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.
The vault identifier. This parameter uses a specific notation:
<creator uid>:<vault_name>
.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: ZenApiKey {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 Cloud Pak for Data instance.
GET /zen-data/v2/secrets
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Query Parameters
The number of secrets to skip before starting to collect the result set.
Default:
0
The number of secrets to return.
Default:
50
Includes preview of secrets.
Default:
false
Sort by the field (for example: sort=secret_name or sort=-secret_name for descending order).\n The supported sort columns include:
secret_name
,type
,description
,created_by
,vault_name
,updated_at
.The type of secret. Vault support per type:
generic
(Internal, HashiCorp),certificate
(Internal, CyberArk, HashiCorp),credentials
(Internal, CyberArk, HashiCorp),key
(Internal, CyberArk, HashiCorp),token
(Internal, HashiCorp)Secret name.
Match on all or any criteria, possible values.
Allowable values: [
any
,all
]Default:
any
If true, returns all secrets when user has manage vaults and secrets permission.
Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Offset of the first secret in the result list. If the offset is not specified in the request, the default is 0.
Limit of the number of secrets returned. If the limit is not specified in the request, the default is 20.
Total number of secrets returned.
Secret collection.
Status Code
Success.
Unauthorized.
Internal Server Error.
No Sample Response
Retrieve the details for a secret
Retrieves the details of a secret specified by a uniform resource name.
GET /zen-data/v2/secrets/{secret_urn}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
Query Parameters
The
exclude_secret_data
parameter can be applied in the query to remove the data section.
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets/<secret_urn>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Update or refresh stored secret
Updates a secret or secret reference to an external vault. Note: You can update the secret itself and its description, but you cannot update the secret_name, vault_name, or type. These fields are immutable and cannot be edited.
PATCH /zen-data/v2/secrets/{secret_urn}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
Query Parameters
Validate secret reference.
Default:
false
Validate secret reference and save.
Default:
false
Sensitive payload to be secured.
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: ZenApiKey {TOKEN}' -d '{ "description": "<description>", "secret": <secret> }'
Delete a secret from vault
Deletes an existing secret or secret reference to an external vault.
DELETE /zen-data/v2/secrets/{secret_urn}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
curl -k -X DELETE 'https://{cpd_cluster_host}/zen-data/v2/secrets/1000330999:oracle-db-login-credentials' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Share a secret
Shares a secret or a secret reference to an external vault to other users and groups.
POST /zen-data/v2/secrets/{secret_urn}/members
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
List of users or groups.
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: ZenApiKey {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 /zen-data/v2/secrets/{secret_urn}/members
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
Query Parameters
The number of secret members to skip before starting to collect the result set.
Default:
0
The number of secrets to return.
Default:
20
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets/<secret_urn>/members' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Offset of the first secret member in the result list, given the order of the collection. If the offset is not specified in the request, the default is 0.
Limit of the number of secret members returned. If the limit is not specified in the request, the default is 25.
Total number of secret members returned.
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 /zen-data/v2/secrets/{secret_urn}/members
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
List of users or/and groups.
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: ZenApiKey {TOKEN}' -H 'Content-Type: application/json' -d '{ "add_members": { "users": [ { "uid": "1000331027", "username": "user22" } ], "groups": [ { "group_name": "access_service_group", "group_id": "10003" } ] }, "remove_members": { "users": [ { "username": "user2", "uid": "1000331002" } ], "groups": [ { "group_name": "provision_group", "group_id": "10002" } ] } }'
Unshare secret
Removes users' or groups' access to secret or a secret reference to an external vault.
DELETE /zen-data/v2/secrets/{secret_urn}/members
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Path Parameters
Unique value identifying the secret for the user.
List of users or/and groups.
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: ZenApiKey {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 /zen-data/v2/secrets/bulk
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
Query Parameters
Comma-separated secret_urns.
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/secrets/bulk?secret_urns=secret-urn-1,secret-urn-2,secret-urn-3' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Retrieve a secret
Returns a secret that you stored in the internal vault for a specified reference. This method returns the entire secret payload in the same manner that it was stored in the vault.
POST /zen-data/v2/serviceInstance/token
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
If this is set to true, then cookie with that instance ID is generated.
Duration (in minutes) the token is valid.
Default:
20
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/serviceInstance/token' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "serviceInstanceID": {serviceInstanceID} }'
Create a volume
Creates a volume instance. Creates a volume instance that can be used to host data files, manage access to Cloud Pak for Data users, and be consumed by other services. You must include the volume instance definition as a JSON string in the HTTP request body. Can be initiated only by a user with the Create service instances permission.
POST /zen-data/v1/volumes
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>Unique ID that is used to identify each transaction.
VolumeInstance metadata artifact that needs to be added to the database.
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_name
is 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:
false
This 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: ZenApiKey {TOKEN}' -d '{ "addon_type": "volumes", "addon_version": "-", "create_arguments": { "metadata": { "file_server": { "start": true, } "volume_type": "EXISTING_PVC", "existing_pvc_name": "user-home-pvc" } }, "namespace": "zen", "display_name": "existing-pv-sample-1" }'
Get a list of volume instances
Retrieves the list of volumes that you have access to.
This method no longer returns the total user count for the volume instance collection when the exclude_user_count query parameter is set to true.
The total user count is still returned as the default behavior for compatibility with an earlier version. However, use the new exclude_user_count parameter if you don't require the total user count information. When you have many service instances, the response time is faster when you use the exclude_user_count parameter.
GET /zen-data/v1/volumes
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
If set to true returns all volume instances. This parameter can be used by an Administrator only.
ID of the volume.
Query by volume name.
Query by namespace.
The number of volumes to skip before starting to collect the result set.
Default:
0
The number of volumes to return.
Default:
20
If set to true, computation of the total number of users that were added to a service instance will be skipped for all instances and omitted from the response.
Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/volumes' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/volumes?display_name=<insert-volume-name>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v1/volumes?fetch_all_instances=true' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Response
Offset of the first instance in the result list, given the order of the collection. If the offset is not specified the default is 0.
Limit of the number of instances returned. If the limit is not specified in the request, the default is 20.
Total number of instances returned.
Service instance collection
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.
Information about the data plane that is associated with the service instance if it is deployed in a remote physical location.
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.
service_instances
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 /zen-data/v2/persistentvolumeclaims/{namespace}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Namespace to get the claims from.
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/persistentvolumeclaims/<namespace>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Update a volume
Updates a volume description. If it is an external SMB volume, this API can be also used to update the volume SMB/CIFS credentials.
PATCH /zen-data/v1/volumes/{display_name}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Name of the volume instance.
curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/v1/volumes/{display_name}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "description":"<new-description>", "cifs_username":"<new-cifs-username>", "cifs_password":"<new-cifs-password>" "supplemental_groups": [<group-id>, <group-id2>, ...] }'
Get all namespaces
Retrieves all the namespaces available in this Cloud Pak for Data deployment.
GET /zen-data/v2/namespaces
Give access to an instance for one or more users
Gives one or more users access to an instance. By default, only the user who created the instance is an administrator. You must include the instance ID as a JSON string in the HTTP request body. You can get the instance ID by using /zen-data/v3/service_instances.
POST /zen-data/v2/serviceInstance/users
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Form Parameters
users
groups
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v2/serviceInstance/users' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "serviceInstanceID":"<volume-instance-ID>", "users":[ { "display_name":"<display-name-of-user>", "role":"<access-level>", "uid":"<uid-of-user>", "username":"<username-of-user>" } ] }'
Revoke access to an instance
Revokes a user's access to the specified instance. You must include the instance ID as a JSON string in the HTTP request body. You can get the instance ID by using /zen-data/v3/service_instances.
DELETE /zen-data/v2/serviceInstance/users
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <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}/zen-data/v2/serviceInstance/users' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "serviceInstanceID":"<volume-instance-ID>", "users":[ "<uid-of-user>" ] }'
Get a list of users with access to an instance
Retrieves the list of users who have access to the specified instance. The role of each user is also returned.
GET /zen-data/v2/serviceInstance/users
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Service Instance ID of the service.
Include profile picture or not.
Default:
false
Roles to query.
Includes group users or not.
Default:
false
curl -k -X GET 'https://{cpd_cluster_host}/zen-data/v2/serviceInstance/users?sID=<volume_instance_id>' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}'
Change a user's role on an instance
Changes the user's role (access level) on the specified instance. You must include the instance ID as a JSON string in the HTTP request body. You can get the instance ID by using /zen-data/v3/service_instances. Note: Can be used only by the administrator of the service instance
PATCH /zen-data/v2/serviceInstance/users/role
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
ServiceInstance metadata artifact that must be added to the database.
curl -k -X PATCH 'https://{cpd_cluster_host}/zen-data/v2/serviceInstance/users/role' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "serviceInstanceID":"<volume-instance-ID>", "roles":[ { "uid":"<uid-of-user>", "newRole":"<new-access-level>" } ] }'
Start a file server with a persistent volume
Starts a service that contains a file server that supports upload, delete, list, and get operations on files.
POST /zen-data/v1/volumes/volume_services/{display_name}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
The display name of the volume instance. You can get the volume instance display name by using
/zen-data/v3/service_instances
.
Volume metadata.
The file server started is run as this UID. This user must be within range 1000320900 to 1000361000 if
cpd-user-scc
is used.
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v1/volumes/volume_services/<display_name>' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ }'
curl -k -X POST 'https://{cpd_cluster_host}/zen-data/v1/volumes/volume_services/<display_name>' -H 'Content-Type: application/json' -H 'Authorization: ZenApiKey {TOKEN}' -d '{ "run_as_user": <uid-of-user> }
Stop a file server on a volume
Stops the Volume File Server REST service on the specified volume instance. You can stop the file server to suspend unnecessary processing when the file server is not needed. Stopping the file server releases the compute resources that are used by the file server. Note: The data in the volume is not deleted.
DELETE /zen-data/v1/volumes/volume_services/{display_name}
Monitor a file server
Monitor a volume's file server status. If the file server in unavailable, you get a 502 Bad Gateway error.
GET /zen-volumes/v1/monitor
Upload file to the volume
Upload a file or create a directory (if no file provided to upload) into the volume. You must specify the target directory for the file on the volume and the path to the source file on the local file system.
PUT /zen-volumes/v1/volumes/files/{file_path}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Path leading upto where the file is uploaded in the volume. This must be url-encoded.
Query Parameters
The default value is
false
. Set the parameter totrue
to extract the contents of.zip
,.tar
,.tar.gz
, or.tgz
files to the specified directory. You can also upload binary-like files, that is, files that do not have a file extension.Default:
false
Set the
make_executable
parameter totrue
to ensure that the file that you uploaded has executable permissions. This operation sets the +x bit across owner, group, and other (world) attributes of the directory. Themake_executable
parameter operates only on singleton files and has no effect on archived file uploads. When you uploaded an archive, the extracted files inherit the permissions from the source from where they were archived.Default:
false
Set to
true
if and only if the name infile_path
is not to be validated or sanitized.Default:
false
The
keep_root_dir
parameter takes effect when uploading.zip
file andextract
is set to true. Ifkeep_root_dir
is set to true, then the extracted file structure will be the exactly same as the original file (root directories will be kept). If the flag is not set or set to false, then the extracted contents will be the same as the old behavior (root directories are removed).Default:
false
Form Parameters
File to be uploaded. If this field is absent then a directory with the file-path is created.
# Upload a file to a volume curl -k -X PUT https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path> -H 'Authorization: ZenApiKey {TOKEN}' -H 'Content-Type: multipart/form-data' -F upFile='@<fully-qualified-file-path>' # Upload and extract the contents of a TAR.GZ file to the specified directory curl -k -X PUT https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?extract=true -H 'Authorization: ZenApiKey {TOKEN}' -H 'Content-Type: multipart/form-data' -F upFile='@<fully-qualified-file-path>' # Upload a file to a specified directory and make it executable curl -k -X PUT 'https://{cpd_cluster_host}/zen-volumes/{display_name}/v1/volumes/files/{directory_path}?make_executable=true' -H 'Authorization: ZenApiKey {TOKEN}' -H 'Content-Type: multipart/form-data' -F upFile=''
Download a file from a volume
Downloads the specified file from the specified volume. You can download a file or an archived directory in the name of your choice. Pass the file name of your choice in the optional override_file_name parameter. You can use the dry_run parameter to check if the asset at the target_file_path exists and return some useful metadata in the response header about the asset. You can also download an entire directory as an archive. Pass the archive type in as the value for the compress parameter in the request. If you issue this command from a web browser, the download prompt is displayed.
GET /zen-volumes/v1/volumes/files/{file_path}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Path leading upto where the file is uploaded in the volume. This must be url-encoded.
Query Parameters
Set to true to probe the file/directory without actually downloading it.
Default:
false
Pass a string here to override the name of the file downloaded.
Specify archive value to compress and download directory.
Allowable values: [
zip
,tar
,tar.gz
]
# Download all files from a directory as a compressed archive curl -k -X GET 'https://{cpd_cluster_host}/zen-volumes/display_name/v1/volumes/files/target_file_path?compress=tar' -H 'Accept: application/json' -H 'Authorization: ZenApiKey {TOKEN}' # Download a file with dry_run=true curl -k -X GET https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?dry_run=true -H 'Authorization: ZenApiKey {TOKEN}' # Download a directory with dry_run=true curl -k -X GET https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?dry_run=true -H 'Authorization: ZenApiKey {TOKEN}'
Delete a directory or file on a volume
Deletes the specified file or directory on the specified volume.
DELETE /zen-volumes/v1/volumes/files/{file_path}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
Path leading upto where the file is uploaded in the volume. This must be url-encoded.
curl -k -X DELETE 'https://{cpd_cluster_host}/zen-volumes/<display_name>/v1/volumes/files/<target_path>' -H 'Authorization: ZenApiKey {TOKEN}'
Copy, move, or rename a file or directory in a volume
Copies, moves, or renames files and directories within a volume.
PUT /zen-volumes/v1/volumes/objects/copy
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Query Parameters
Set to
false
if you do not want to retain a copy of the object at thesource_path
(equivalent to amv
inUNIX
). This value defaults to true, which keeps the object at thesource_path
.Default:
true
Set to
true
ifdestination_path
in 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_path
with the same name as in thesource_path
, creating any directories specified in thedestination_path
.Default:
false
Set to
true
if 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_name
directory.Destination path of file or directory relative to
volume_name
directory.
curl -k -X PUT 'https://{cpd_cluster_host}/zen-volumes/<volume_name>/v1/volumes/objects/copy' -H 'Authorization: ZenApiKey {TOKEN}' -H 'Content-Type: application/json' -d '{ "source_path": "foo/bar", "destination_path": "baz" }
Get a list of the directories and files on a volume
Retrieves the list of all directories and files on the specified volume. You can use the recursive parameter to list contents from the <directory_path> recursively. The API supports a boolean query parameter tree. If set to true, the API returns the contents as a tree structure representing the actual directory structure. To use the tree option, you must set recursive to true. You can also optionally use the include_details query parameter to list the contents of the <directory_path> as an array of objects and their metadata.
GET /zen-volumes/v1/volumes/directories/{directory_path}
Request
Custom Headers
Authorization: ZenApiKey | Bearer <token>
Examples:Authorization: ZenApiKey <token>Authorization: Bearer <token>
Path Parameters
The directory for which you want to display the contents. If you are referring to a nested directory, use URL encoding. For example, to create a reference to a directory called
Shared files/analytics projects
, enter:Shared%20files%2Fanalytics%20projects
.
Query Parameters
The default value is
false
. Set the parameter to true to list the contents of the specified directory path recursively.Default:
false
The default value is
false
. Set the parameter totrue
to have the API contents returned as a tree structure that represents the actual directory structure.Default:
false
(To Be Deprecated Soon) Set to true if you want the response to indicate the type of entity (for example: file or directory)
Default:
false
If set to
true
, the API lists the contents from thedirectory_path
as 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: ZenApiKey {TOKEN}'