Managing secrets with the Credentials and Secrets API

Introduction

Security is critical when services use secrets such as database access credentials, SSL certificates, API keys, and authentication tokens. Customers are also subject to regulatory compliance that requires reporting and auditing of privileged credential usage, and forensic analysis of access. Storing and accessing credentials in plain text on applications and services poses a serious security risk. You need tools that provide access and secrets management, both for system identities and user identities.

The Vaults and Secrets Management APIs introduce a centralized mechanism that is hardened by data encryption, secure access control, authorization checks, and auditing, which addresses credential management in Cloud Pak for Data across all services. You can securely store and tightly control access to secrets (such as passwords, tokens, API keys, encryption keys, and certificates) to protect access to sensitive data. You can store credentials such as passwords, API keys, tokens, certificates, or other sensitive information within a vault. You can also access vaults by using Python in Notebooks, scripts, and other code to store and retrieve secrets.

Vaults and secrets management can also be done by using a user interface. For more information, see Managing secrets and vaults.

Generating an authorization token

You can use this API to generate an authorization token. This access token is used in subsequent API calls. See Generating an authorization token. See also Get authorization token in the IBM® Cloud Pak for Data Platform API.

API for managing Vaults

API for managing Secrets

• Store a secret

  Store and secure a secret or secret reference for an external vault in an internal vault by using this API.

  Endpoint

  /zen-data/v2/secrets

  Method

  POST

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "<secret-name>",
      "description": "<description>",
      "secret": <secret>,
      "members": <members>,
      "type": "certificate|credentials|generic|key|token",
      "vault_urn": "0000000000:internal"
    }' 

  Parameters

  Parameter	Type	Description
  secret_name	String	A name for your secret. This name must be unique across all the secrets that you own and that are currently stored in the vault. It can contain a maximum of 110 characters.
  description (Optional)	String	A short description for your secret.
  secret	Free-form object (JSON)	The secret is schema-less, which means you can enter any type of information as valid key-value pairs. The format that you use to store the secret is used when you retrieve your secret.
  type	Enumerated type: generic (default) certificate credentials key token	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
  vault_urn	String	The identifier of the vault where you would like to store the secret.
  members	List	The list of users or groups that can access the secret.

  If the query parameter vaildate=true is set, integration with the external vault is validated. To validate and save use the query parameter vaildate_and_save=true. Validation is only used for secret references and external vaults. It is strongly recommended to store a secret reference with validation, as your input will be tested.

  Sample request: Generic

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "generic-secret",
      "description": "This is my generic secret",
      "secret": {
        "generic": {
           "my_secret" : "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ"
        }
      },
      "type": "generic",
      "vault_urn": "0000000000:internal"
  }' 
  

  Sample response

  {
      "secret_urn": "1000330999:generic-secret"
  } 
  

  Sample request: Credentials

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "oracle-db-login-credentials",
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "credentials": {
              "username": "aaa",
              "password": "bbb"
          }
      },    
      "type": "credentials",
      "vault_urn": "0000000000:internal"
  }' '
  

  Sample response

  {
      "secret_urn": "1000330999:oracle-db-login-credentials"
  }

  Sample request: Certificate

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "oracle-db-certificate",
      "description": "This is my oracle db certificate",
      "secret": {
          "certificate": {
              "cert": "<Certificate>",
              "key": "<Optional - Private key>"
          } 
      },
      "type": "certificate",
      "vault_urn": "0000000000:internal"
  }'
  

  Sample response

  {
      "secret_urn": "1000330999:oracle-db-certificate"
  }
  

  Sample request: Key

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "artifactory-api-key",
      "description": "This is my api_key to artifactory",
      "secret": {
        "key": "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ"
      },
      "type": "key",
      "vault_urn": "0000000000:internal"
  }'
  

  Sample response

  {
      "secret_urn": "1000330999:artifactory-api-key"
  }

  Sample request: Token

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "service-token",
      "description": "This is my token for service",
      "secret": {
        "token": "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ"
      },
      "type": "token",
      "vault_urn": "0000000000:internal"
  }' 
  

  Sample response

  {
      "secret_urn": "1000330999:service-token"
  }

  Sample request: Secret reference, CyberArk AAM - credentials

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "oracle-db-login-credentials",
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "safe": "Test", 
  	"account_name" : "sample-user-01"
      },    
      "type": "credentials",
      "vault_urn": "1000330999:cyberark-aam-vault"
  }' 
  

  Sample response

  {
      "secret_urn": "1000330999:oracle-db-login-credentials"
  }

  Sample request: Validate a CyberArk AAM secret reference - credentials

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets?validate=true \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "oracle-db-login-credentials",
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "safe": "Test", 
  	"account_name" : "sample-user-01"
      },    
      "type": "credentials",
      "vault_urn": "1000330999:cyberark-aam-vault"
  }' 
  

  Sample response

  {
      "secret_urn": "1000330999:oracle-db-login-credentials"
  }

  Sample request: Validate and save a CyberArk AAM secret reference - credentials

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets?validate_and_save=true \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "oracle-db-login-credentials",
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "safe": "Test", 
  	"account_name" : "sample-user-01"
      },    
      "type": "credentials",
      "vault_urn": "1000330999:cyberark-aam-vault"
  }' 
  

  Sample response

  {
      "secret_urn": "1000330999:oracle-db-login-credentials"
  }

  Sample request: HashiCorp - credentials

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets \
    -H 'Authorization: Bearer <my-deployment-url>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "oracle-db-login-credentials",
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "path": "/secret/data/cpd_access"
      },    
      "type": "credentials",
      "vault_urn": "1000330999:hashicorp-vault"
  }'  
  

  Sample response

  {
      "secret_urn": "1000330999:oracle-db-login-credentials"
  }

  Sample request: Validate a HashiCorp secret reference - credentials

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets?validate=true \
    -H 'Authorization: Bearer <my-deployment-url>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "oracle-db-login-credentials",
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "path": "/secret/data/cpd_access"
      },    
      "type": "credentials",
      "vault_urn": "1000330999:hashicorp-vault"
  }'  
  

  Sample response

  {
      "secret_urn": "1000330999:oracle-db-login-credentials"
  }

  Sample request: Validate and save a HashiCorp secret reference - credentials

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets?validate_and_save=true \
    -H 'Authorization: Bearer <my-deployment-url>' \
    -H 'Content-Type: application/json' \
   -d '{
      "secret_name": "oracle-db-login-credentials",
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "path": "/secret/data/cpd_access"
      },    
      "type": "credentials",
      "vault_urn": "1000330999:hashicorp-vault"
  }'  
  

  Sample response

  {
      "secret_urn": "1000330999:oracle-db-login-credentials"
  }

• Retrieve a list of all your secrets

  List all secret references that are stored in a platform by using this API.

  Endpoint

  /zen-data/v2/vaults/<vault_name>/secrets

  Method

  GET

  curl -k -X GET \
    https://<my-deployment-url>/zen-data/v2/secrets \
    -H 'Authorization: Bearer <authorization-token>'
  

  Parameters

  Parameter	Description
  sort	Field to sort by (sort=created_by or sort=-created_by for descending order). The supported sort columns include: secret_name description type created_by vault_name updated_at
  secret_name	Name of secret.
  match	Match on any or allcriteria. (Default: any)
  offset	The number of secrets to skip before the API starts to collect the result set. (Default: 0)
  limit	The number of secrets to return. (Default: 50)

  Sample request

  curl -k -X GET \
    'https://<my-deployment-url>/zen-data/v2/secrets?sort=-created_at&offset=0&limit=2' \
    -H 'Authorization: Bearer <authorization-token>'
  

  Sample response

  {
      "limit": 2,
      "offset": 0,
      "secrets": [
          {
              "created_at": "2021-03-27T19:44:47.729751Z",
              "created_by": "New Admin",
              "description": "Oracle db creds",
              "secret_name": "oracle_db_login_credentials",
              "secret_urn": "1000330999:oracle_db_login_credentials",
              "type": "credentials",
              "updated_at": "2021-03-27T19:44:47.729751Z",
              "vault_name": "internal",
              "vault_urn": "0000000000:internal"
          },
          {
              "created_at": "2021-03-27T02:58:04.916859Z",
              "created_by": "New Admin",
              "description": "Artifactory key",
              "secret_name": "artifactory_api_key",
              "secret_urn": "1000330999:artifactory_api_key",
              "type": "key",
              "updated_at": "2021-03-27T02:58:04.916859Z",
              "vault_name": "internal",
              "vault_urn": "0000000000:internal"
          }
      ],
      "total_count": 9
  }

  From the response, you can capture the secret_urn, vault_urn, and the reference to your secret, which follows the <uid>:<secret_name> notation.

  You must provide this secret_urn in some of the subsequent API calls. This API is intended for UI experiences. You can always form the secret_urn notation by intuition if you know the creator uid and secret name.

• Retrieve a secret

  Retrieve a secret that was previously stored in a vault by using this API.

  Endpoint

  /zen-data/v2/secrets/<secret_urn>

  Method

  GET

  curl -k -X GET \
    https://<deployment-url>/zen-data/v2/secrets/<secret_urn> \
    -H 'Authorization: Bearer <authorization-token>'
  

  Parameters

  Parameter

  Description

  secret_urn

  This parameter identifies and associates the secret with the user. This parameter follows a specific notation - <creator uid>:<secret_name>. It is important to follow this notation when you retrieve a secret. exclude_secret_data can be applied in the query to remove the data section. Note - this query parameter can only be used for external vaults and secrets. Both vault_name and secret_name is what was used in the request body when you stored the secret.

  Sample request: Credentials

  curl -k -X GET \
    'https://<my-deployment-url>/zen-data/v2/secrets/999:oracle_db_login_credentials' \
    -H 'Authorization: Bearer <authorization-token>'
  

  Sample response

  {
      "data": {
          "secret": {
              "credentials": {
                  "password": "xxxx",
                  "username": "myapp"
              }
          }
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "Admin",
          "description": "Oracle db creds",
          "secret_name": "string122",
          "secret_urn": "1000330999:oracle_db_login_credentials",
          "type": "credentials",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }

  Sample request: Key

  curl -k -X GET \
    'https://<my-deployment-url>/zen-data/v2/secrets/999:artifactory_api_key' \
    -H 'Authorization: Bearer <authorization-token>' \
  

  Sample response

  {
      "data": {
          "secret": {
              "key": "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ",
          }
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "999",
          "description": "Artifactory key",
          "secret_name": "artifactory_api_key",
          "secret_urn": "1000330999:artifactory_api_key",
          "type": "key",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }

  Sample request: Generic

  curl -k -X GET \
    'https://<my-deployment-url>/zen-data/v2/secrets/1000330999:generic-secret' \
    -H 'Authorization: Bearer <authorization-token>' \
  

  Sample response: Version 2 format (default)

  {
      "data": {
          "secret": {
  	    "generic" : {
              "my_secret" : "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ"
  	    }
          }
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "1000330999",
          "description": "Generic secret",
          "secret_name": "generic-secret",
          "secret_urn": "1000330999:generic-secret",
          "type": "generic",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }

  Sample response: Version 1

  To enable V1 Format, set VAULT_CONFIG_GENERIC_SECRET_FORMAT_V1: "true" in the product-configmap.

  {
      "data": {
          "secret": {
  	    "generic" : {
              "my_secret" : "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ"
  	    }
          }
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "1000330999",
          "description": "Generic secret",
          "secret_name": "generic-secret",
          "secret_urn": "1000330999:generic-secret",
          "type": "generic",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }

  Sample request: HashiCorp secret

  curl -k -X GET \
    'https://zen-core-api-svc:4444/v2/secrets/1000331031:vault-hashi-generic-secret-1' \
    -H 'Authorization: Bearer <authorization-token>' \

  Sample response: Generic version 1 format

  {
    "data":{
      "secret":{
        "generic":{
          "value": {
            "hello":"world"
          }
        }
      },
      "secret_reference":{
        "path":"/secret/data/generic_hello"
      }
    },
    "metadata":{
      "created_at":"2022-05-05T14:41:31.750747Z",
      "created_by":"user4",
      "description":"Create from api test",
      "owner_uid":"1000331031",
      "secret_name":"vault-hashi-generic-secret-1",
      "secret_urn":"1000331031:vault-hashi-generic-secret-1",
      "type":"generic",
      "updated_at":"2022-05-05T14:41:31.750747Z",
      "vault_name":"vault-hashi-generic-secret-vault",
      "vault_urn":"1000331031:vault-hashi-generic-secret-vault"
    }
  }

  Sample response: Generic version 2 format

  {
    "data":{
      "secret":{
        "generic":{
          "hello":"world"
        }
      },
      "secret_reference":{
        "path":"/secret/data/generic_hello"
      }
    },
    "metadata":{
      "created_at":"2022-05-05T14:41:31.750747Z",
      "created_by":"user4",
      "description":"Create from api test",
      "owner_uid":"1000331031",
      "secret_name":"vault-hashi-generic-secret-1",
      "secret_urn":"1000331031:vault-hashi-generic-secret-1",
      "type":"generic",
      "updated_at":"2022-05-05T14:41:31.750747Z",
      "vault_name":"vault-hashi-generic-secret-vault",
      "vault_urn":"1000331031:vault-hashi-generic-secret-vault"
    }
  }

  Sample request: Cyberark AAM Non-JSON secret

  curl -k -X GET \
    'https://zen-core-api-svc:4444/v2/secrets/1000331031:vault-cyberark-generic-secret-1' \
    -H 'Authorization: Bearer <authorization-token>' \

  Sample response: Non-JSON generic version 1 format

  {
    "data":{
      "secret":{
        "generic":{
          "value":"..."
        }
      },
      "secret_reference":{
        "safe": "Test",
        "account_name" : "sample-user-02"
      }
    },
    "metadata":{
      ...
    }
  }

  Sample response: Non-JSON generic version 2 format

  {
    "data":{
      "secret":{
        "generic":{
          "account_username":"aws_test",
          "content":"..."
        }
      },
      "secret_reference":{
        "safe": "Test",
        "account_name" : "sample-user-02"
      }
    },
    "metadata":{
      ...
    }
  }

  Sample request: Cyberark AAM JSON generic secret

  curl -k -X GET \
    'https://zen-core-api-svc:4444/v2/secrets/1000331031:vault-cyberark-generic-secret-2' \
    -H 'Authorization: Bearer <authorization-token>' \

  Sample response: JSON generic version 1 format

  {
    "data":{
      "secret":{
        "generic":{
          "value":{
            "type":"service_account"
          }
        }
      },
      "secret_reference":{
        "safe": "Test",
        "account_name" : "sample-user-03"
      }
    },
    "metadata":{
      ...
    }
  }
  

  Sample response: JSON generic version 2 format

  {
    "data":{
      "secret":{
        "generic":{
          "account_username":"sample-user-01",
          "type":"service_account"
        }
      },
      "secret_reference":{
        "safe": "Test",
        "account_name" : "sample-user-03"
      }
    },
    "metadata":{
      ...
    }
  }

  The metadata in the response body includes information such as the secret_name and secret_urn. The returned data includes the secret itself in the exact same manner it was requested to be stored in previously.

• Retrieve bulk secrets

  In a single API call, retrieve secret details for up to 20 secrets.

  Endpoint

  /zen-data/v2/secrets/bulk?secret_urns=<comma-separated-secret-urn(s)>

  Method

  GET

  curl -k -X GET \
    GET /zen-data/v2/secrets/bulk?secret_urns=secret-urn-1,secret-urn-2,secret-urn-3 \
    -H 'Authorization: Bearer <authorization-token>'

  Parameters

  Parameter	Type	Description
  secret_urn	String	This parameter identifies and associates the secret with the user. This parameter follows a specific notation - <creator uid>:<secret_name>.

  Sample request

  curl -k -X GET \
    'https://<my-deployment-url>/zen-data/v2/secrets/bulk?secret_urns=1000330999:oracle_db_login_credentials,1000330999:artifactory_api_key,1000330999:generic-secret' \
    -H 'Authorization: Bearer <authorization-token>'

  Sample response

  [
    {
      "data": {
          "secret": {
              "credentials": {
                  "password": "xxxx",
                  "username": "myapp"
              }
          }
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "Admin",
          "description": "Oracle db creds",
          "secret_name": "string122",
          "secret_urn": "1000330999:oracle_db_login_credentials",
          "type": "credentials",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
    },
    {
      "data": {
          "secret": {
              "key": "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ",
          }
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "999",
          "description": "Artifactory key",
          "secret_name": "artifactory_api_key",
          "secret_urn": "1000330999:artifactory_api_key",
          "type": "key",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
    },
    {
      "data": {
          "secret": {
  	    "generic" : {
  	       "value" : {
  	          "my_secret" : "VugP1PCcPyX6cbvfHYFQmnY0KJyR7w4aosjGpeDY8uY3mokfkXcy0hBvJbm9FRSQ"
  	       }
  	    }
          }
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "1000330999",
          "description": "Generic secret",
          "secret_name": "generic-secret",
          "secret_urn": "1000330999:generic-secret",
          "type": "generic",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
    }
  ]

• Update a secret

  Update a secret or a secret reference for an external vault by using this API. 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.

  Endpoint

  /zen-data/v2/secrets/<secret_urn>

  Method

  PATCH

  curl -k -X PATCH \
    https://<my-deployment-url>/zen-data/v2/secrets/<secret_urn> \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "description": "<description>",
      "secret": <secret>
    }' 

  Parameters

  Parameter	Type	Description
  secret_urn	String	This parameter identifies and associates the secret with the user. This parameter follows a specific notation - <vault_name>:<secret_name>. It is important to follow this notation when you update a secret. Both vault_name and secret_name is what you used in the request body when you stored the secret.
  description (Optional)	String	A short description of your secret.
  secret	Free-form object (JSON)	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.

  If the query parameter vaildate=true is set, integration with the external vault is validated. To validate and save use the query parameter vaildate_and_save=true. Validation is only used for secret references and external vaults. It is strongly recommended to update a secret reference with validation, as your input will be tested.

  Sample request

  curl -k -X PATCH \
    https://<my-deployment-url>/zen-data/v2/secrets/1000330999:oracle-db-login-credentials \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "description": "Updating my login credentials for the Oracle instance",
      "secret": {
          "credentials": {
              "username": "aaa-new",
              "password": "bbb-new"
          }
      },    
      "type": "credentials",
      "vault_urn": "0000000000:internal"
  }' 
  

  Sample response

  {
      "data": {
          "secret": {
              "credentials": {
                  "username": "aaa-new",
                  "password": "bbb-new"
              }
          }
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "Admin",
          "description": "Oracle db creds",
          "secret_name": "oracle_db_login_credentials",
          "secret_urn": "1000330999:oracle_db_login_credentials",
          "type": "credentials",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }
  

  Sample request: CyberArk AAM secret reference - credentials

  curl -k -X PATCH \
    https://<hostname>/zen-data/v2/secrets/1000330999:oracle-db-login-credentials \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "safe": "Test", 
  	"account_name" : "sample-user-01"
      }
  }' 
  

  Sample response

  {
      "data": {
          "secret": {
              "credentials": {
                  "username": "aaa",
                  "password": "bbb"
              }
          },
          "secret_reference": {
  	    "safe": "Test", 
  	    "account_name" : "sample-user-01"
          }	
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "Admin",
          "description": "Oracle db creds",
          "secret_name": "oracle_db_login_credentials",
          "secret_urn": "1000330999:oracle_db_login_credentials",
          "type": "credentials",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }

  Sample request: Validate a CyberArk AAM secret reference - credentials

  curl -k -X PATCH \
    https://<hostname>/zen-data/v2/secrets/1000330999:oracle-db-login-credentials?validate=true \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "safe": "Test", 
  	"account_name" : "sample-user-01"
      }
  }' 
  

  Sample response

  {
      "data": {
          "secret": {
              "credentials": {
                  "username": "aaa",
                  "password": "bbb"
              }
          },
          "secret_reference": {
  	    "safe": "Test", 
  	    "account_name" : "sample-user-01"
          }	
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "Admin",
          "description": "Oracle db creds",
          "secret_name": "oracle_db_login_credentials",
          "secret_urn": "1000330999:oracle_db_login_credentials",
          "type": "credentials",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }

  Sample request: Validate and save a CyberArk AAM secret reference - credentials

  curl -k -X PATCH \
    https://<hostname>/zen-data/v2/secrets/1000330999:oracle-db-login-credentials?validate_and_save=true \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "safe": "Test", 
  	"account_name" : "sample-user-01"
      }
  }' 
  

  Sample response

  {
      "data": {
          "secret": {
              "credentials": {
                  "username": "aaa",
                  "password": "bbb"
              }
          },
          "secret_reference": {
  	    "safe": "Test", 
  	    "account_name" : "sample-user-01"
          }	
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "Admin",
          "description": "Oracle db creds",
          "secret_name": "oracle_db_login_credentials",
          "secret_urn": "1000330999:oracle_db_login_credentials",
          "type": "credentials",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }

  Sample request: HashiCorp secret reference - credentials

  curl -k -X PATCH \
    https://<hostname>/zen-data/v2/secrets/1000330999:oracle-db-login-credentials \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "path": "/secret/data/cpd_access"
      }
  }'  
  

  Sample response

  {
      "data": {
          "secret": {
              "credentials": {
                  "username": "aaa",
                  "password": "bbb"
              }
          },
          "secret_reference": {
  	    "path": "/secret/data/cpd_access" 
          }	
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "Admin",
          "description": "Oracle db creds",
          "secret_name": "oracle_db_login_credentials",
          "secret_urn": "1000330999:oracle_db_login_credentials",
          "type": "credentials",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }

  Sample request: Validate a HashiCorp secret reference - credentials

  curl -k -X PATCH \
    https://<hostname>/zen-data/v2/secrets/1000330999:oracle-db-login-credentials?validate=true \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "path": "/secret/data/cpd_access"
      }
  }'  
  

  Sample response

  {
      "data": {
          "secret": {
              "credentials": {
                  "username": "aaa",
                  "password": "bbb"
              }
          },
          "secret_reference": {
  	    "path": "/secret/data/cpd_access" 
          }	
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "Admin",
          "description": "Oracle db creds",
          "secret_name": "oracle_db_login_credentials",
          "secret_urn": "1000330999:oracle_db_login_credentials",
          "type": "credentials",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }

  Sample request: Validate and save a HashiCorp secret reference - credentials

  curl -k -X PATCH \
    https://<hostname>/zen-data/v2/secrets/1000330999:oracle-db-login-credentials?validate_and_save=true \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "description": "These are my login credentials for the Oracle instance with SSL",
      "secret": {
          "path": "/secret/data/cpd_access"
      }
  }'  
  

  Sample response

  {
      "data": {
          "secret": {
              "credentials": {
                  "username": "aaa",
                  "password": "bbb"
              }
          },
          "secret_reference": {
  	    "path": "/secret/data/cpd_access" 
          }	
      },
      "metadata": {
          "created_at": "2021-03-27T02:27:26.822658Z",
          "created_by": "Admin",
          "description": "Oracle db creds",
          "secret_name": "oracle_db_login_credentials",
          "secret_urn": "1000330999:oracle_db_login_credentials",
          "type": "credentials",
          "updated_at": "2021-03-27T02:27:26.822658Z"
      }
  }

• Delete a secret

  Delete an existing secret or secret reference from an external vault.

  Note: This action is irreversible and a secret cannot be revived after it is deleted.

  Endpoint

  /zen-data/v2/secrets/<secret_urn>

  Method

  DELETE

  curl -k -X DELETE \
    https://<my-deployment-url>/zen-data/v2/secrets/<secret_urn> \
    -H 'Authorization: <authorization-token>'
  

  Parameters

  Parameter	Description
  secret_urn	This parameter identifies and associates the secret with the user. This parameter follows a specific notation - <creator uid>:<secret_name>.

  Sample request

  curl -k -X DELETE \
    https://<my-deployment-url>/zen-data/v2/secrets/1000330999:oracle-db-login-credentials \
    -H 'Authorization: Bearer <authorization-token>'
  

  Sample response

  {
      "secret_urn": "1000330999:oracle-db-login-credentials"
  }

  If you try to retrieve or update a secret after the secret is deleted successfully, the API returns a 404 Not Found error.

API for sharing Secrets

• Share a secret

  Share a secret or a secret reference for an external vault to other users and groups by using this API.

  Endpoint

  /zen-data/v2/secrets/<secret_urn>/members

  Method

  POST

  curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets/<secret_urn>/members \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "users": [
        {
          "username": <username>,
          "uid": <uid>
        }
      ],
      "groups": [
        {
          "group_name": <group-name>,
          "group_id": <group-id>
        }
      ]
    }' 

  Parameters

  Parameter	Type	Description
  secret_urn	String	This parameter identifies and associates the secret with the user. This parameter follows a specific notation - <vault_name>:<secret_name>.
  users (Optional)	List of objects (JSON)	The list of users that can access a secret.
  groups (Optional)	List of objects (JSON)	The list of groups that can access a secret.

  Sample request

   curl -k -X POST \
    https://<my-deployment-url>/zen-data/v2/secrets/1000330999:secret-name/members \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "users": [
        {
          "username": "user2",
          "uid": "1000331002"
        }
      ],
      "groups": [
        {
          "group_name": "provision_group",
          "group_id": "10002"
        }
      ]
    }'

  Sample response

  {
      "secret_urn": "1000330999:secret-name"
  }
  

• Retrieve your secret members

  Retrieve a list of all your secret shared members for a secret or a secret reference (external vault) by using this API.

  Endpoint

  /zen-data/v2/secrets/<secret_urn>/members

  Method

  GET

  curl -k -X GET \
    https://<my-deployment-url>/zen-data/v2/secrets/<secret_urn>/members \
    -H 'Authorization: Bearer <authorization-token>'

  Parameters

  Parameter	Description
  secret_urn	This parameter identifies and associates the secret with the user. This parameter follows a specific notation - <vault_name>:<secret_name>.
  offset	The number of secrets to skip before the API starts to collect the result set. (Default: 0)
  limit	The number of secrets to return. (Default: 50)

  Sample request

  curl -k -X GET \
    https://<my-deployment-url>/zen-data/v2/secrets/1000330999:secret-name/members \
    -H 'Authorization: Bearer <authorization-token>'

  Sample response

  {
      "limit": 20,
      "members": {
          "groups": [
              {
                  "group_id": "10002",
                  "group_name": "provision_group"
              }
          ],
          "users": [
              {
                  "email": "--",
                  "uid": "1000330999",
                  "username": "admin"
              },
              {
                  "email": "jerry@ibm.com",
                  "uid": "1000331002",
                  "username": "user2"
              }
          ]
      },
      "offset": 0,
      "total_count": 0
  }

• Unshare a secret

  Remove users or groups access to secret or a secret reference to an external vault by using this API.

  Endpoint

  /zen-data/v2/secrets/<secret_urn>/members

  Method

  DELETE

  curl -k -X DELETE \
    https://<my-deployment-url>/zen-data/v2/secrets/<secret_urn>/members \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "users": [
        {
          "username": <username>,
          "uid": <uid>
        }
      ],
      "groups": [
        {
          "group_name": <group-name>,
          "group_id": <group-id>
        }
      ]
    }'

  Sample request

  curl -k -X DELETE \
    https://<my-deployment-url>/zen-data/v2/secrets/1000330999:secret-name/members \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "users": [
        {
          "username": "user2",
          "uid": "1000331002"
        }
      ],
      "groups": [
        {
          "group_name": "provision_group",
          "group_id": "10002"
        }
      ]
    }' 

  Sample response

  {
      "secret_urn": "1000330999:secret-name"
  }

• Share and unshare a secret

  Share and remove users or groups access to a secret or a secret reference to an external vault by using a single API call.

  Endpoint

  /zen-data/v2/secrets/<secret_urn>/members

  Method

  PUT

  curl -k -X PUT \
    https://<my-deployment-url>/zen-data/v2/secrets/<secret_urn>/members \
    -H 'Authorization: Bearer <authorization-token>' \
    -H 'Content-Type: application/json' \
   -d '{
      "add_members": {
        "users": [
          {
            "username": <username>,
            "uid": <uid>
          }
        ],
        "groups": [
          {
            "group_name": <group-name>,
            "group_id": <group-id>
          }  
        ]
      },
      "remove_members": {
        "users": [
          {
            "username": <user-username>,
            "uid": <user-uid>
          }
        ],
        "groups": [
          {
            "group_name": <group-name>,
            "group_id": <group-id>
          }  
        ]
      }
    }'

  Parameters

  Parameter	Type	Description
  secret_urn	String	This parameter identifies and associates the secret with the user. This parameter follows a specific notation - <vault_name>:<secret_name>.
  add_members (Optional)	List of objects (JSON)	The list of users and groups that can access a secret.
  remove_members (Optional)	List of objects (JSON)	The list of users and groups can no longer access a secret.

  Sample request

  curl -k -X PUT \
    https://<my-deployment-url>/zen-data/v2/secrets/1000330999:oracle-db-login-credentials99/members \
    -H 'Authorization: Bearer <authorization-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"
          }  
        ]
      }
    }'

  Sample response

  {
      "1000330999:oracle-db-login-credentials99"
  }

Python methods

Python methods within Jupyter runtime environments can be used to retrieve secrets stored a vault. In order to train and test models from an external data source, users may need to connect the external data source with a Jupyter notebook. To connect to a data source, users might have to enter their authentication details in plain text. This poses a security risk, especially if a user wants to collaborate with other users in the same Notebook.

With the Python methods that are included in the Credentials and Secrets management service, you can store your credentials in the vault and then securely retrieve these credentials during run time of your Notebook without the need to enter your credentials in clear text.

You can invoke Python methods in Jupyter runtime environments to retrieve secrets:

• Retrieve a list of secrets stored in a vault

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

  Method

  get_my_secrets_v2()

  Example

  my_secrets = icpd_util.get_my_secrets_v2()
  my_secrets_json = json.dumps(my_secrets, indent=4)
  print(my_secrets_json)

  Sample response

  [
    {
      "created_at": "2021-12-02T20:05:25.212698Z",
      "created_by": "admin",
      "description": "csdc",
      "owner_uid": "1000330999",
      "secret_name": "secret03",
      "secret_urn": "1000330999:secret03",
      "type": "credentials",
      "updated_at": "2021-12-02T20:05:25.212698Z",
      "vault_name": "internal",
      "vault_urn": "0000000000:internal"
    },
    {
      "created_at": "2021-12-02T20:08:01.882514Z",
      "created_by": "admin",
      "description": "dcsdcv",
      "owner_uid": "1000330999",
      "secret_name": "secret04",
      "secret_urn": "1000330999:secret04",
      "type": "credentials",
      "updated_at": "2021-12-02T20:08:01.882514Z",
      "vault_name": "internal",
      "vault_urn": "0000000000:internal"
    },
    {
      "created_at": "2021-12-02T18:14:07.516686Z",
      "created_by": "admin",
      "owner_uid": "1000330999",
      "secret_name": "test-secret",
      "secret_urn": "1000330999:test-secret",
      "type": "credentials",
      "updated_at": "2021-12-02T18:14:07.516686Z",
      "vault_name": "internal",
      "vault_urn": "0000000000:internal"
    },
    {
      "created_at": "2021-12-02T20:04:52.419517Z",
      "created_by": "admin",
      "owner_uid": "1000330999",
      "secret_name": "test-secret2",
      "secret_urn": "1000330999:test-secret2",
      "type": "credentials",
      "updated_at": "2021-12-02T20:04:52.419517Z",
      "vault_name": "internal",
      "vault_urn": "0000000000:internal"
    }
  ]

• Retrieve a secret

  Returns a secret that you have 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.

  Method

  get_my_secret(secret_reference)

  Parameters

  Parameter	Type	Description
  secret_urn	String	This parameter identifies and associates the secret with the user. This parameter follows a specific notation - <vault_name>:<secret_name>.

  Example

  my_test_secret = icpd_util.get_my_secret_details_v2(secret_urn)
  my_test_secret_creds=my_test_secret['data']['secret']['credentials']
  my_db_username = my_test_secret_creds['username']
  my_db_password = my_test_secret_creds['password']