Managing secrets with the Credentials and Secrets API

Important: IBM Cloud Pak® for Data Version 4.7 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.7 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.

You can also access vaults by using Python in Notebooks, scripts, and other code to store and retrieve secrets. For more information, see the IBM Cloud Pak for Data Core Python Client.

You can also manage secrets and vaults by using a user interface. For more information, see Managing secrets and vaults.

Required role
An authorization token is created for a specific user ID. That user ID determines the permissions that are applied in the API calls. For example, the API returns only the content for those secrets that are visible to the particular user ID.
Authentication
To use the Credentials and Secrets API, you must authenticate to Cloud Pak for Data. See Generating an API authorization token. See also Get authorization token in the IBM Cloud Pak for Data Platform API.

Methods for managing vaults

Store an external vault configuration

Create an external vault integration by using this API.

For more information, see Store external vault configuration.
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 you own by using this API. If you have the Manage vaults and secrets permission, you can list all the vaults in the platform.

For more information, see Retrieve details about external vault integrations.
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.

For more information, see Retrieve a vault.
Sample Request: Internal vault
Cloud Pak for Data identifies internal vaults by their special vault URN. For example, 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.

For more information, see Update external vault configuration.
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.

For more information, see Delete external vault integration.
Note: Deleting a vault deletes all of its associated secrets.
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
Use this API to initiate transfer_vault_ownership for external vaults to other users. There are two steps for transferring vault ownership.
  1. Users with the permission Manage vaults and secrets can initiate transfer_vault_ownership to other users, by using this API. For more information, see Initiate the transfer of ownership of a vault.
    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. For more information, see Transfer vault to user.

    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.

    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://vault.example.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
}

Methods for managing secrets

Store a secret

Store and secure a secret or secret reference for an external vault in an internal vault.

For more information, see Store secret or reference.
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.

For more information, see Get a list of all secrets.
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 might need to 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.

For more information, see Retrieve the details for a 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 in the same format that it stored originally.
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.

For more information, see Update or refresh stored secret.
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.

For more information, see Delete secret from vault.
Note: This action is irreversible and a secret cannot be revived after it is deleted.
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.

Methods 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.

For more information, see Share 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.

For more information, see Get secret members.
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.

For more information, see Unshare secret.
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.

For more information, see Share or unshare 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"
}