Managing secrets with the Credentials and Secrets API

Important: IBM Cloud Pak® for Data Version 4.6 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.6 reaches end of support. For more information, see Upgrading IBM Software Hub in the IBM Software Hub Version 5.1 documentation.

Safeguard credentials and secrets with access control and audit logging by using the Credentials and Secrets Management APIs.

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.

Authentication

Required role: An authorization token is generally created for a specific user ID. That user ID determines the permissions applied in the API calls. For example, the API returns only the content for those secrets that are visible to the particular user ID.

To use the Credentials and Secrets API, you must authenticate to Cloud Pak for Data. See Generating an authorization token or API key. See also Get authorization token in the IBM Cloud Pak for Data Platform API.

Using the API to manage vaults

Store an external vault configuration
Create an external vault integration by using this API.
Endpoint
/zen-data/v2/vaults
Method
POST
curl -k -X POST \
  https://<my-deployment-url>/zen-data/v2/vaults \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{
 
      "description": "<description>",
      "details": <details>,
      "test_data": <test-data>,
      "type": "cyberark_aam_cert|hashicorp_token",
      "vault_name": "<vault-name>"
      
  }'
Parameters
Parameter Type Description
vault_name String A name for your vault. This name must be unique across all the vaults that you own and that are currently stored in the vault.
description (Optional) String A short description for your vault.
details Object (JSON) CyberArk fields
vault_address
Vault address or URL
app_id
Application ID
client_key
Base-64 encode value of TLS key
client_certificate
Base-64 encode value of TLS certificate
HashiCorp fields
vault_address
Vault address or URL
access_token
Vault token
type String The external vault type, either the cyberark_aam_cert or hashicorp_token.
test_data Free-form object (JSON) 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 parameter vaildate_and_save=true.
Important: You must store a vault with validation because your input is tested.
Sample request: CyberArk AAM vault integration
curl -k -X POST \
  https://<my-deployment-url>/zen-data/v2/vaults \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -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"      
}'
Sample response: HTTP 200
{
    "vault_urn": "1000330999:My-cyberarkaam-vault"
}
Sample request: HashiCorp vault integration
curl -k -X POST \
  https://<my-deployment-url>/zen-data/v2/vaults \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{    
    "description": "This is hashicorp vault",
    "details": { 
		"vault_address": "https://hashivault.com",
		"access_token" : "token"
    },
    "type": "hashicorp_token",
    "vault_name": "My-hashicorp-token-vault"      
}'
Sample response: HTTP 200
{
    "vault_urn": "1000330999:My-hashicorp-token-vault"
}
Sample request: Validate CyberArk AAM vault integration
curl -k -X POST \
  https://<my-deployment-url>/zen-data/v2/vaults?validate=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -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",
    "test_data" : {"safe": "Test", "account_name" : "sample-user-01"}
}'
Sample response: HTTP 201
{
    "vault_urn": "1000330999:My-cyberarkaam-vault"
}
Sample request: Validate and save a CyberArk AAM vault integration
curl -k -X POST \
  https://<my-deployment-url>/zen-data/v2/vaults?validate_and_save=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -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",
    "test_data" : {"safe": "Test", "account_name" : "sample-user-01"}
}'
Sample response: HTTP 201
{
    "vault_urn": "1000330999:My-cyberarkaam-vault"
}
Sample request: Validate HashiCorp vault integration
curl -k -X POST \
  https://<my-deployment-url>/zen-data/v2/vaults?validate=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{    
    "description": "This is hashicorp vault",
    "details": { 
		"vault_address": "https://hashivault.com",
		"access_token" : "token"
    },
    "type": "hashicorp_token",
    "vault_name": "My-hashicorp-token-vault",
    "test_data" : {"path": "/secret/data/hello"}
}'
Sample response: HTTP 201
{
    "vault_urn": "1000330999:My-hashicorp-token-vault"
}
Sample request: Validate and save a HashiCorp vault integration
curl -k -X POST \
  https://<my-deployment-url>/zen-data/v2/vaults?validate_and_save=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{    
    "description": "This is hashicorp vault",
    "details": { 
		"vault_address": "https://hashivault.com",
		"access_token" : "token"
    },
    "type": "hashicorp_token",
    "vault_name": "My-hashicorp-token-vault",
    "test_data" : {"path": "/secret/data/hello"}
}'
Sample response: HTTP 200
{
    "vault_urn": "1000330999:My-hashicorp-token-vault"
}
Retrieve a list of your vaults
List all vaults that are owned by you using this API. If you have the Manage vaults and secrets permission, you can list all the vaults in the platform.
Endpoint
/zen-data/v2/vaults
curl -k -X GET \
  https://<my-deployment-url>/zen-data/v2/vaults \
  -H 'Authorization: Bearer <authorization-token>'
Method
GET
Parameters
Parameter Description
sort Field to sort by (sort=created_by or sort=-created_by for descending order). The supported sort columns are:
  • vault_name
  • owned_by
  • created_by
  • uploaded_at
  • total_secrets
provider_name Comma-separated provider names (CyberArk AAM, HashiCorp).
vault_name Name of vault.
match Match on any or all criteria. (Default: any)
Sample request
curl -k -X GET \
  'https://<my-deployment-url>/zen-data/v2/vaults?limit=2&sort=updated_at&provider_name=cyber,hashi' \
  -H 'Authorization: Bearer <authorization-token>'
Sample response
{
    "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"
        }
    ]
}

The vault_urn, as shown in the sample response, is required in some of the subsequent API calls.

Retrieve a vault
Retrieve a vault's details by using this API.
Endpoint
/zen-data/v2/vaults/<vault_urn>
Method
GET
curl -k -X GET \
  https://<my-deployment-url>/zen-data/v2/vaults/<vault_urn> \
  -H 'Authorization: Bearer <authorization-token>'
Parameters
Parameter Description
vault_urn The path parameter that the vaults micro-service uses to identify and associate the vault with the user. This parameter uses a specific notation: <creator uid>:<vault_name>.
Sample Request: Internal vault
Internal vaults are identified by their special vault urn: 0000000000:internal. 
curl -k -X GET \
  'https://<my-deployment-url>/zen-data/v2/vaults/0000000000:internal' \
  -H 'Authorization: Bearer <authorization-token>'
Sample response
{
    "data": null,
    "metadata": {
        "created_at": "2021-05-18T12:41:17.9981Z",
        "created_by": "admin",
        "invalid_auth": false,
        "invalid_owner": false,
        "owned_by": "admin",
        "provider_name": "Platform vault",
        "secret_preview": "",
        "total_secrets": 0,
        "updated_at": "2021-05-18T12:41:17.9981Z",
        "vault_name": "internal",
        "vault_type": "internal",
        "vault_urn": "0000000000:internal"
    }
}
Sample request: CyberArk AAM vault
curl -k -X GET \
  'https://<my-deployment-url>/zen-data/v2/vaults/1000330999:test-cyberark-aam-cert-vault-0' \
  -H 'Authorization: Bearer <authorization-token>'
Sample response
{
    "data": {
        "vault": {
            "app_id": "testappid",
            "client_certificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCmNlcnQKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQoK",
            "client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQprZXkKLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0K",
            "vault_address" : "https://vault.myorg.com:14506"
        }
    },
    "metadata": {
        "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",
        "owner_uid": "1000330999",	
        "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"
    }
}
Sample request: HashiCorp vault
curl -k -X GET \
  'https://<hostname>/zen-data/v2/vaults/1000330999:test-hashicorp-token-vault-0' \
  -H 'Authorization: Bearer <authorization-token>'
Sample response
{
    "data": {
        "vault": {
            "access_token": "token",
            "vault_address": "https://hashivault.com"
        }
    },
    "metadata": {
        "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",
        "owner_uid": "1000330999",
        "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"
    }
}
Sample request: HashiCorp vault is scheduled to be transferred to other users
curl -k -X GET \
  'https://<hostname>/zen-data/v2/vaults/1000330999:test-hashicorp-token-vault-0' \
  -H 'Authorization: Bearer <authorization-token>'
Sample response
{
    "data": {
        "vault": {
             "access_token": "",
             "vault_address": "https://hashivault.com"
        }
    },
    "metadata": {
        "created_at": "2021-05-18T02:19:37.237302Z",
        "created_by": "admin",
        "description": "creating sample vault test-hashicorp-token-vault-0",
        "invalid_auth": true, // set to true
        "invalid_owner": false,
        "owned_by": "admin",
        "owner_uid": "1000330999",	
        "provider_name": "Hashicorp - Token Authentication",
        "requires_auth_update": true, // set to true
        "scheduled_owner_uid": "1000331007", // scheduled owner uid
        "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"
    }
}
Update a vault
Owners can update external vault integrations by using this API.
Endpoint
/zen-data/v2/vaults/<vault_urn>
Method
PATCH
curl -k -X PATCH \
  https://<my-deployment-url>/zen-data/v2/vaults/<vault_urn> \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{
    "description": "<description>",
    "details": <details>,
    "test_data": <test-data>
  }'
Parameters
Parameter Type Description
vault_urn String The path parameter that the vaults micro-service uses to identify and associate the vault with the user. This parameter uses a specific notation: <creator uid>:<vault_name>.
description (Optional) String A short description for your vault.
details Free-form object (JSON) The object that contains the sensitive details for connecting to the external vault.
test_data Free-form object (JSON) 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 parameter vaildate_and_save=true.
Important: You must store a vault with validation because your input is tested.
Sample request: CyberArk AAM vault
curl -k -X PATCH \
  'https://<my-deployment-url>/zen-data/v2/vaults/1000330999:test-cyberark-aam-cert-vault-0' \
  -H 'Authorization: Bearer <authorization-token>'  \
  -H 'Content-Type: application/json' \
 -d '{    
    "description": "This is cyberark aam vault update",
    "details": { 
		"vault_address": "https://vault.myorg.com:14506",
		"app_id": "testappid-new",
		"client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQprZXkKLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0K",
		"client_certificate" : "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCmNlcnQKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQoK"    
    }
}'
Sample response
{
    "data": {
        "vault": {
            "details": {
                "app_id": "testappid-new",
                "client_certificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCmNlcnQKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQoK",
                "client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQprZXkKLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0K",
                "vault_address": "https://vault.myorg.com:14506"
            }
        }
    },
    "metadata": {
        "created_at": "2021-05-18T02:19:37.258828Z",
        "created_by": "admin",
        "description": "This is cyberark aam vault update",
        "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"
    }
}
Sample request: HashiCorp vault
curl -k -X PATCH \
  'https://<my-deployment-url>/zen-data/v2/vaults/1000330999:test-hashicorp-token-vault-0' \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{    
    "description": "Update hashicorp vault description",
    "details": { 
		"vault_address": "https://hashivault.com",
		"access_token" : "token-new"
    }
}'
Sample response
{
    "data": {
        "vault": {
            "details": {
                "access_token": "token",
                "vault_address": "https://hashivault.com"
            }
        }
    },
    "metadata": {
        "created_at": "2021-05-18T02:19:37.237302Z",
        "created_by": "admin",
        "description": "Update hashicorp vault description",
        "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"
    }
}
Sample request: Validate a CyberArk AAM vault integration
curl -k -X PATCH \
  https://<my-deployment-url>/zen-data/v2/vaults/1000330999:My-cyberarkaam-vault?validate=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{    
    "description": "Udapting cyberark aam vault",
    "details": { 
		"vault_address": "https://vault.myorg.com:14506",
		"app_id": "testappid",
		"client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQprZXkKLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0K",
		"client_certificate" : "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCmNlcnQKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQoK"    
    },
    "test_data" : {"safe": "Test", "account_name" : "sample-user-01"}
}'
Sample response: HTTP 201
{
    "vault_urn": "1000330999:My-cyberarkaam-vault"
}
Sample request: Validate a HashiCorp vault integration
curl -k -X PATCH \
  https://<my-deployment-url>/zen-data/v2/vaults/1000330999:My-hashicorp-token-vault?validate=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{    
    "description": "Updating hashicorp vault",
    "details": { 
		"vault_address": "https://hashivault.com",
		"access_token" : "token"
    },
    "test_data" : {"path": "/secret/data/hello"}
}'
Sample response: HTTP 201
{
    "vault_urn": "1000330999:My-hashicorp-token-vault"
}
Sample request: Validate and save a CyberArk AAM vault integration
curl -k -X PATCH \
  https://<my-deployment-url>/zen-data/v2/vaults/1000330999:My-cyberarkaam-vault?validate_and_save=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{    
    "description": "Udapting cyberark aam vault",
    "details": { 
		"vault_address": "https://services-uscentral.skytap.com:14506",
		"app_id": "testappid",
		"client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQprZXkKLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0K",
		"client_certificate" : "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCmNlcnQKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQoK"    
    },
    "test_data" : {"safe": "Test", "account_name" : "sample-user-01"}
}'
Sample response: HTTP 200
{
    "vault_urn": "1000330999:My-cyberarkaam-vault"
}
Sample request: Validate and save a HashiCorp vault integration
curl -k -X PATCH \
  https://<my-deployment-url>/zen-data/v2/vaults/1000330999:My-hashicorp-token-vault?validate_and_save=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{    
    "description": "Updating hashicorp vault",
    "details": { 
		"vault_address": "https://hashivault.com",
		"access_token" : "token"
    },
    "test_data" : {"path": "/secret/data/hello"}
}'
Sample response: HTTP 200
{
    "vault_urn": "1000330999:My-hashicorp-token-vault"
}
Delete a vault
Owners can delete external vault integrations by using this API.
Note: Deleting a vault deletes all of its associated secrets.
Endpoint
/zen-data/v2/vaults/<vault_urn>
Method
DELETE
curl -k -X DELETE \
  https://<my-deployment-url>/zen-data/v2/vaults/<vault_urn> \
  -H 'Authorization: Bearer <authorization-token>'
Parameters
Parameter Description
vault_urn The path parameter that the vaults micro-service uses to identify and associate the vault with the user. This parameter uses a specific notation: <creator uid>:<vault_name>.
Sample request: CyberArk AAM vault
curl -k -X DELETE \
  'https://<my-deployment-url>/zen-data/v2/vaults/1000330999:My-cyberarkaam-vault' \
  -H 'Authorization: Bearer <authorization-token>'
Sample response
{
    "vault_urn": "1000330999:My-cyberarkaam-vault"
}
Sample request: HashiCorp vault
curl -k -X DELETE \
  'https://<my-deployment-url>/zen-data/v2/vaults/1000330999:My-hashicorp-token-vault' \
  -H 'Authorization: Bearer <authorization-token>'
Sample response
{
    "vault_urn": "1000330999:My-hashicorp-token-vault"
}
Transferring vault ownership
This API lets you initiate transfer_vault_ownership for external vaults to other users. There are two steps involved in transferring vault ownership.
  1. Users with the permission Manage vaults and secrets can initiate transfer_vault_ownership to other users, by using this API.
    Endpoint
    /zen-data/v2/vaults/<vault-urn>/transfers
    Method
    POST
    curl -k -X POST \
  https://<hostname>/zen-data/v2/vaults/<vault-urn>/transfers \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{
 
      "new_owner_uid": "<new_owner_uid>"
      
  }'
    Parameters
    Parameter Description
    vault_urn The path parameter that the vaults micro-service uses to identify and associate the vault with the user. This parameter uses a specific notation: <creator uid>:<vault_name>.
    new_owner_uid The new owner's unique identifier.
    Sample request
    curl -k -X POST \
  https://<hostname>/zen-data/v2/vaults/<vault-urn>/transfers \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{
 
      "new_owner_uid": "1000331007"
      
  }'
    Sample response
    {
   "metadata":{
      "created_at":"2022-02-24T21:36:45.677238Z",
      "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-1,vault-hashi-uc-trans-vault-secret-2,vault-hashi-uc-trans-vault-secret-3",
      "total_secrets":3,
      "updated_at":"2022-02-24T21:36:45.677238Z",
      "vault_name":"vault-hashi-uc-trans-vault",
      "vault_type":"hashicorp_token",
      "vault_urn":"1000331031:vault-hashi-uc-trans-vault"
   }
}
  2. The scheduled owner can start the transfer by updating the vault ownership to become the new owner of the vault and any secrets in it, if any exist. The previous owner will still have access to all of the vault's secrets.

    If the vault has 100 secrets or less, the transfer is completed instantly. However, if the vault has more than 100 secrets, the transfer is scheduled and executed asynchronously. The transfer should complete within 3 minutes. If the process does not complete within 10 minutes add the query parameter force=true to the URL and run the transfer again.

    Endpoint
    /zen-data/v2/vaults/<vault-urn>/transfers
    Method
    PATCH
    curl -k -X PATCH \
  https://<hostname>/zen-data/v2/vaults/<vault-urn>/transfers \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{
 
     "vault_address": "<vault-address>",
     "access_token": "<token>"
      
  }'
    Parameters
    Parameter Description
    vault_urn The path parameter that the vaults micro-service uses to identify and associate the vault with the user. This parameter uses a specific notation: <creator uid>:<vault_name>.
    vault_address The vault address or URL.
    access_token The vault token.
    Sample request: HashiCorp vault
    curl -k -X PATCH \
  https://<hostname>/zen-data/v2/vaults/1000331031:vault-hashi-uc-trans-vault/transfers \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
 -d '{
 
     "vault_address": "http://zen-vault-hc1.fyre.ibm.com:8200",
     "access_token": "token"
      
  }'
    Sample response with 100 secrets or less: HTTP 200
    {
   "metadata":{
      "created_at":"2022-05-05T14:41:38.198956Z",
      "created_by":"user4",
      "description":"",
      "invalid_auth":false,
      "invalid_owner":false,
      "owned_by":"user7",
      "owner_uid":"1000331007",
      "provider_name":"Hashicorp",
      "requires_auth_update":false,
      "secret_preview":"vault-hashi-uc-trans-vault-secret-1,vault-hashi-uc-trans-vault-secret-2,vault-hashi-uc-trans-vault-secret-3",
      "total_secrets":3,
      "updated_at":"2022-05-05T14:41:38.198956Z",
      "vault_name":"vault-hashi-uc-trans-vault",
      "vault_type":"hashicorp_token",
      "vault_urn":"1000331031:vault-hashi-uc-trans-vault"
   }
}
    Sample response with more than 100 secrets: HTTP 202
    {
  // empty body
}

Using the API to manage 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 all vaults. 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.
Important: Validation is used for secret references and external vaults only. You must store a secret reference with validation because your input is 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/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
The exclude_secret_data parameter can be applied in the query to remove the data section.
Note: This query parameter can be used for external vaults and secrets only.
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 that 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.
Important: Validation is only used for secret references and external vaults. You must update a secret reference with validation because your input is 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.

Using the API to share 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

You can use Python methods within Jupyter runtime environments to retrieve secrets that are stored a vault. To train and test models from an external data source, users might 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.

If you are running the Notebook in a namespace that is different from the cpddev namespace, you must set the fully-qualified zen-core-api URL by using icpd_util.set_zencoreapi_host('https://zen-core-api-svc.<instance>.svc:4444') where _<instance>_ is the name of the instance namespace. For example, using the cpddev namespace, you can add this line to your Notebook.
icpd_util.set_zencoreapi_host('https://zen-core-api-svc.cpddev.svc:4444')

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 that you 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 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']