Create and manage user accounts, user groups, roles, events, vaults, cards, and volumes on IBM® Cloud Pak for Data by using the Cloud Pak for Data REST API.

Introduction

As an administrator, you are responsible for determining and implementing the best approach for authenticating and managing the Cloud Pak for Data platform.

You can perform the following tasks by using the Cloud Pak for Data REST API:

Manage user and user group permissions : A Cloud Pak for Data administrator can create and manage roles, which grant permissions to users and groups on the platform.

: A user can have multiple roles. The roles can be assigned directly to a user or can be assigned to the user through a user group. If a user has multiple roles, the user has all of the permissions from all of the roles that are assigned to them.

: User groups make it easier to manage many users with similar access requirements. For example, if you know that 20 different users are going to collaborate on a project and they all need the Data steward role, you can add them to a group that is assigned the Data steward role. If a member of the group leaves the company, you can remove the user from the group, rather than look for and update all of the assets that the user has access to.

Create and manage user profiles : Authenticated users can perform tasks such as updating their own user-profile information, generating an API key, or changing their password.

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

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

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

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

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

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

Authentication

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

Using Authorization: ZenApiKey token

With a platform API key, you can access everything that you would typically be able to access when you log in to the Cloud Pak for Data web client.

To generate a platform API key through the user experience:

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.

ErrorResponse

| Name | Description | |-----------------------------------------------------------------------------------|--------------------------------| | _messageCode_
String | An identifier of the response. | | statusCode
Integer | The HTTP response code. | | exception
String | An explanation of the problem. | | message
String | An explanation of the _messageCode_. |

Configuring monitors and alerts

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

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

Creating custom cards for the home page

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

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

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

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

Examples of template types

Template types:

The donut template illustrates an array of values as percentages in a donut chart.
The bartemplate 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.

Versioning

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

Change log

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

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

Related information

Cloud Pak for Data API | IBM Cloud API Docs