Managing secrets and vaults

Cloud Pak for Data includes an internal vault that you can use to store secrets. You can also connect to external vaults where you already store sensitive information as secrets.

You can use secrets in Cloud Pak for Data when you create connections to make sure that sensitive data, such as credentials, are secure and encrypted.

Overview of secrets and vaults
Services that support connections that use secrets from vaults
Internal vault
External vaults
Bridges to external vaults
Vaults and secrets APIs

Overview of secrets and vaults

A secret contains sensitive data. You can use secrets to store various information, such as:

Usernames and passwords
SSL certificates
API keys
Authentication tokens
JDBC URLs

A vault is a secure place to store and manage secrets. Cloud Pak for Data includes an internal vault. If you have a supported enterprise-grade vault, you can also connect to external vaults.

Secrets offer several advantages over traditional plain-text entry:

The information in the secret is stored in a secure and encrypted environment that conforms to your organization's policies.
The services and connections that use the secret do not have direct access to the information in the secret.
The information in the secret can be updated once. The change is automatically picked up by all services or connections that use the secret.

Services that support connections that use secrets from vaults

You can use secrets when you create connections to external data sources and to services.

The following services support connections that use secrets instead of plain-text credentials:

Analytics Engine powered by Apache Spark
Data Privacy
Data Refinery
DataStage®
Db2® Big SQL
Decision Optimization
IBM® Knowledge Catalog
IBM Match 360 with Watson™
RStudio® Server Runtimes
SPSS® Modeler
Watson Machine Learning Accelerator
Watson OpenScale
Watson Query
Watson Studio
Watson Studio Runtimes

Tools that support shared credentials in connections that use secrets from vaults

Most Cloud Pak for Data services require personal credentials if the credentials are stored in a secret. However, you can use shared credentials from a secret with the following services and tools:

Notebooks (Watson Studio).
You can generate or write your own code to access connections to load data to a notebook.

For more information about using secrets in connections, see Using secrets from vaults in connections.

Internal vault

Cloud Pak for Data includes an internal vault by default. However, a cluster administrator or instance administrator can optionally disable the internal vault.

Data that is stored in this vault is encrypted. However, the internal vault is intended primarily for proof-of-concept demonstrations. In production environments, it is strongly recommended that you connect to an external vault.

What permissions do I need to add secrets to the internal vault?

You do not need any permissions to add secrets to the internal vault. All Cloud Pak for Data users can add secrets to the internal vault.

You can manage your secrets in the internal vault from the Administration > Configurations and settings > Vaults and secrets page. For more information, see Adding secrets to the internal vault.

Note: A user with the Manage vaults and secrets permission can perform the following tasks:

View the list of secrets (but not the content of the secrets) in the internal vault
Delete secrets from the internal vault

What can I store in the internal vault?

You can store the following types of data in a secret in the internal vault:

Username and password
Key
Token
SSL Certificate
Kerberos credentials
Custom secrets

Can I share my secrets with other users?

By default, you can share secrets with other users.

External vaults

You can integrate Cloud Pak for Data with the following types of external vaults:

CyberArk Application Access Manager (CyberArk AAM)
HashiCorp

After you integrate with an external vault, you can specify which secrets in the vault can be used in Cloud Pak for Data. Secrets are created and stored in the external vault. The contents of the secrets are not exposed in Cloud Pak for Data, and the secrets cannot be modified in Cloud Pak for Data. Secrets in an external vault can be managed only through the external vault interface.

Important: Cloud Pak for Data connections and services can retrieve secrets from the external vault only on behalf of an authorized user.

What permissions do I need to use secrets from an external vault?

To integrate Cloud Pak for Data with an external vault or add secrets from an external vault, you must have the Add vaults permission.

For more information, see these resources:

Note: A user with the Manage vaults and secrets permission can:

View the list of connected vaults
View the list of the secrets (but not the content of the secrets) in each vault
Remove external vaults
Remove secrets added from an external vault

What types of secrets can I use from an external vault?

The type of secrets that you add from an external vault depend on the type of vault that you integrate with:

CyberArk AAM

Username and password
Key
Custom secret

For more information about CyberArk vaults, see the CyberArk documentation.

HashiCorp

Username and password
Key
Token
SSL certificate
Custom secret

Can I share my secrets with other users?

To share secrets with other users, you must have the Share secrets permission. However, a cluster administrator or an instance administrator can optionally disable secret sharing.

Bridges to external vaults

If you want to use another external vault, you can use the vault bridge SDK to create a vault bridge and integrate Cloud Pak for Data with an external vault. The vault bridge SDK dynamically plugs in to the platform with extensions to integrate with an external vault. Then, Cloud Pak for Data users can fetch the credentials from the vault to access data in their data sources. The vaults bridge SDK includes examples of bridging to the following external vaults:

AWS Secrets Manager
Microsoft Azure Key Vault
IBM Cloud® Secrets Manager

A typical workflow that explains the steps of using a vault bridge.

A Cloud Pak for Data service user logs in to the console and requests data processing on data in the data source.
The Cloud Pak for Data service requests a secret identifier from the Platform connection.
The Cloud Pak for Data service receives a secret identifier.
Using the secret identifier, the Cloud Pak for Data service requests secret details from the Platform Core API.
The Platform Core API validates user access, determines the vault bridge type by using the secret identifier, and routes the request to one of the follow vault bridges.
Embedded vault bridge

5a. The bridge requests secret details directly from the vault.

SDK based vault bridge
- 5y. The Platform Core API forwards the request to the vault bridge.
- 5z. The vault bridge requests secret details from the vault.
The Cloud Pak for Data service receives the secret details.
Using the secret details and the connection information, the Cloud Pak for Data service requests data from the data source.
The Cloud Pak for Data service receives the data and performs the requested operation on the retrieved data.

For more information, see the Vaults Bridge SDK at https://github.com/IBM/zen-secrets-vaults.

Vaults and secrets APIs

You can safeguard credentials and secrets with access control and audit logging by using the Vaults and secrets APIs.

Required role: An authorization token is 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 Vaults and secrets APIs, 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.

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"
   }
}

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"
}