vania-janet/multiturn-rag-retrieval-data huggingface dataset:
If you are using jq or other tools, review the difference in the response structure.



The secret data is at the root of the secret and not under the secret_data field.



 Comparing v1 and v2 Curl examples 

Compare the following examples to see the changes between the v1 Curl code snippet and how the code must look like in v2.

v1 example

curl -X POST --location --header "Authorization: Bearer ${iam_token}"
--header "Accept: application/json"
--header "Content-Type: application/json"
--data '{
"metadata": {
"collection_type": "application/vnd.ibm.secrets-manager.secret+json",
"collection_total": 1
},
"resources": [
{
"name": "example-arbitrary-secret",
"description": "Extended description for this secret.",
"secret_group_id": "bc656587-8fda-4d05-9ad8-b1de1ec7e712",
"payload": "secret-data",
"labels":
"dev", "us-south"
],
"expiration_date": "2030-01-01T00:00:00Z"
}
]
}'
"{base_url}/api/v1/secrets/{secret_type}"
Show more

v2 example

curl -X POST --location
--header "Authorization: Bearer {iam_token}"
--header "Accept: application/json"
--header "Content-Type: application/json"
--data '{
"description": "Extended description for this secret.",
"expiration_date": "2030-01-01T00:00:00Z",
"labels": [
"dev", "us-south"
],
"name": "example-arbitrary-secret",
},
{
"name": "lock-for-app-2",
"description": "Test lock for secret in a custom secret group.",
"attributes": {
"key": "value"
}
}
]
}'
Show more

Lock a secret version exclusively.

curl -X POST "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/{secret_type}/locks/{secret_id}/lock_exclusive" -H 'X-Vault-Token: {Vault-Token}'
-H 'Content-Type: application/json' -D '{
"locks": [
{
"name": "lock-for-app-1",
"description": "Test lock for secret in the default secret group.",
"attributes": {
"key": "value"
}
}
]
}'

Lock a secret version exclusively and delete previous version data.

curl -X POST "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/{secret_type}/locks/{secret_id}/lock_exclusive_delete" -H 'X-Vault-Token: {Vault-Token}'
-H 'Content-Type: application/json' -D '{
"locks": [
{
"name": "lock-for-app-1",
"description": "Test lock for secret in the default secret group.",
"attributes": {
"key": "value"
}
}
]
}'





 Example response 

A request to lock the current version of a secret that is in the default secret group returns the following response:

{
"request_id": "cad3f223-ec90-1e8e-9408-7fc3c9c50b86",
Using an API key with Secrets Manager to authorize a project to deploy an architecture 

When you configure your deployable architecture, you are required to select an authentication method. You can use an API key that is stored as a secret to authorize a project to deploy in an account.

A secret is a piece of sensitive information, for example an API key, password, or any type of credential that you might use to access a confidential system. You can use a secret in IBM Cloud® Secrets Manager as a way to manage API keys dynamically and store them securely in your own dedicated instance.

Though it is possible to add your API key directly into your configuration, it is not recommended, as the API key displays in your project.json file and is visible to anyone who exports it.



 Before you begin 



1. Make sure that you are assigned the required permissions to create the project tooling resources within the account in addition to permission to create projects:





* The Editor role on the IBM Cloud Projects service.
* The Editor and Manager role on the IBM Cloud® Schematics service.
* The Viewer role on the resource group for the project.



For more information about access and permissions, see [Assigning users access to projects](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-access-project).



1. [Create a Secrets Manager service instance](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-create-instance&interface=ui) in your IBM Cloud account. To create a secret, you must have the Writer role or higher on the Secrets Manager service.
2. After you create your secret instance, make sure that you select Other secret type to add an arbitrary secret. For information about creating an abitrary secret, see [Creating arbitrary secrets in the UI](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-arbitrary-secrets&interface=ui). Your arbitrary secret must contain the API key. The API key must be created in the target account that you want to deploy to.
3.
"anyKey": "anyValue"
}
}'
Show more







 Migrating Node applications 

If you use Node, review the following steps and examples to migrate to Secrets Manager API v2.



1. Update your package.json file to use the latest version (2.0.0).
2. Change the required command to @ibm-cloud/secrets-manager/secrets-manager/v2.
3. For each operation that you're using, remove the type and the metadata and resources wrapper from the resource JSON object.



Responses contain only the secret JSON object or a secrets field in case of a list. They do not contain the resources object.



 Comparing v1 and v2 Node examples 

Compare the following examples to see the changes between the v1 Node code snippet and how the code must look like in v2.

v1 example

let res = await secretsManager.createSecret({
secretType: 'username_password',
'metadata': {
'collection_type': 'application/vnd.ibm.secrets-manager.secret+json',
'collection_total': 1,
},
'resources': [
{
'name': 'example-username-password-secret',
'description': 'Extended description for this secret.'
'username': 'user123'
'password': '123456789',
'labels': 'label1', 'label2'],
'expiration_date': '2030-04-01T09:30:00Z'
},
],
});
Show more

v2 example

let res = await secretsManager.createSecret({
secretPrototype: {
description: 'Extended description for this secret.',
experation_date: '2030-04-01T09:30:00Z",
labels: ['label1', 'label2'],
name: 'example-username-password-secret',
[IAM credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials) iam_credentials* Dynamic A dynamically generated service ID and API key that can be used to access an IBM Cloud service that requires IAM authentication. 
 [Key-value secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-key-value) kv Static Pieces of sensitive data that is structured in JSON format that you can use to access an application or resource. 
 [SSL/TLS certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-certificates) imported_cert <br>public_cert* <br>private_cert* Static A type of digital certificate that can be used to establish communication privacy between a server and a client. In Secrets Manager, you can store the following types of certificates.<br><br><br><br> * Imported certificates: Certificates that you import to the service.<br> * Public certificates: Certificates that you order from a third-party certificate authority, for example Let's Encrypt.<br> * Private certificates: Certificates that you generate by using a private certificate authority that you manage in Secrets Manager.<br><br><br> 
 [User credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-user-credentials) username_password Static Username and password values that you can use to log in or access an application or resource. 



* Requires an [engine configuration](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secrets-engines) before secrets can be created in the service.



 Supported features by secret type 

The following table compares and contrasts some common characteristics between the secret types.



Table 2. Feature comparison between secret types

 Arbitrary secrets IAM credentials User credentials Key-value secrets Imported certificates Public certificates Private certificates 

 [Automatic rotation](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-automatic-rotation) !
<br>This secret is also used as a Git repository access secret in the CLI and Code repo access in the console. 
 Transport Layer Security (TLS) A secret that contains a signed TLS certificate, including all its intermediate certificates, and its corresponding private key from a certificate authority (CA). <br>Use TLS secrets when you work with [custom domain mappings](https://cloud.ibm.com/docs/codeengine?topic=codeengine-domain-mappings) in Code Engine. 









 Creating secrets 

Use secrets to provide sensitive information to your apps or jobs. Secrets are defined in key-value pairs and the data that is stored in secrets is encoded.



 Creating a secret from the console 

Learn how to create secrets from the Code Engine console.



 Creating a generic secret from the console 

Learn how to create generic secrets from the Code Engine console that can be consumed by jobs or apps as environment variables.

Before you begin, [create a project](https://cloud.ibm.com/docs/codeengine?topic=codeengine-manage-project).



1. After your project is in Active status, click the name of your project on the [Code Engine Projects page](https://cloud.ibm.com/codeengine/projects).
2. From the Components page, click Secrets and configmaps.
3. From the Secrets and configmaps page, click Create to create your secret.
4. From the Create config page, complete the following steps:



1. Select the Secret option.
2. Provide a name; for example, mysecret.
3. Click Add key-value pair. Specify one or more key-value pairs for this secret. For example, specify one key as secret1 with the value of mysecret1 and specify another key as secret2 with the value of target-secret. The name that you choose for your key does not need to be the same as the name of your environment variable. Notice that the value for the key is hidden, but it can be viewed if needed.



5. Click Create to create the secret.
By using references to secrets that are managed by secret providers such as Key Protect, your secret values are centralized and stored securely in a single location. This approach resolves secrets sprawl and proliferation, and means that you can update secrets without updating your toolchain. When you use secret references, the actual secret value is resolved when the toolchain runs by dynamically retrieving it from Key Protect. This approach is useful when you must rotate the value of your toolchain secrets periodically.





 Adding a Key Protect tool integration to your toolchain template 

You can add a Key Protect tool integration to your toolchain template by adding a service definition to the toolchain.yml file in your template repo. This file is the design blueprint for your toolchain and includes all of the tool integrations that are available when you create a toolchain instance based on that template. To customize an existing toolchain template to include a Key Protect tool integration, insert a YAML definition.

kp-tool:
service_id: keyprotect
parameters:
name: kp-compliance-secrets
region: us-south
resource-group: default
instance-name: ffs-secrets

For more information about customizing toolchain templates, see [Create a template for a custom toolchain](https://www.ibm.com/cloud/architecture/tutorials/create-a-template-for-a-custom-toolchain).

In certain scenarios, you can add a Key Protect tool integration dynamically while creating a toolchain. For example, if you click New to mint a new API key, you can select the Save this key in a secrets store for reuse checkbox to save the API key in a Key Protect instance to use it again later. If you do not already have a Key Protect instance, a new instance is created for you.





 Authorizing your toolchain to access secrets 

References to secrets that are stored in Key Protect are dynamically resolved when the toolchain runs. To access the required secrets, you must authorize your toolchain to access the Key Protect instance.
* remove_previous_and_delete: Carries out the same function as remove_previous, but also permanently deletes the data of the previous secret version if it doesn't have any locks.



ibmcloud secrets-manager secret-locks-bulk-create --id ID --locks LOCKS [--mode MODE]



 Command options 

--id (string)
: The ID of the secret. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/.

--locks ([SecretLockPrototype]](https://cloud.ibm.com/docs/cli?topic=cli-secrets-manager-clicli-secret-lock-prototype-example-schema))
: The locks data to be attached to a secret version. Required.

The maximum length is 1000 items. The minimum length is 0 items.

Provide a JSON string option or specify a JSON file to read from by providing a filepath option that begins with a @, e.g. --locks=@path/to/file.json.

--mode (string)
: Set the lock mode. Allowable values: remove_previous, and remove_previous_and_delete. Use remove_previous to create a lock that clears existing locks with matching names. Use remove_previous_and_delete to also delete data from the previous version.

Allowable values are: remove_previous, remove_previous_and_delete.





 Example
},
{
"version_id": "5bf89b0c-df55-c8d5-7ad6-8816951c6784",
"version_alias": "previous",
"locks":
"lock-1",
"lock-2"
],
"payload_available": true
}
]
}

For more information about the required and optional request parameters, see the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2lock-secret).





 Creating locks on the previous secret version 

The following request creates two locks on the previous version of a secret. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.

curl -X POST
-H "Authorization: Bearer {iam_token}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
"locks": [
{
"name": "lock-1",
"description": "Lock for consumer 1.",
"attributes": {
"key": "value"
}
},
{
"name": "lock-2",
"description": "Lock for consumer 2.",
"attributes": {
"key": "value"
}
}
]
}' "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions/{version_id}/locks_bulk"

A successful response returns details about the new locks, along with other metadata.

{
"secret_id": "0cf4addb-7a90-410b-a3a7-a15bbe2b7909",
A lock can be used to prevent a secret from being deleted or modified while it's in use by your applications. A successful request attaches a new lock to your secret, or replaces a lock of the same name if it already exists. Additionally, you can use this operation to clear any matching locks on a secret by using one of the following optional lock modes:



* remove_previous: Removes any other locks with matching names if they are found in the previous version of the secret.
* remove_previous_and_delete: Carries out the same function as remove_previous, but also permanently deletes the data of the previous secret version if it doesn't have any locks.



ibmcloud secrets-manager secret-version-locks-bulk-create --secret-id SECRET-ID --id ID --locks LOCKS [--mode MODE]



 Command options 

--secret-id (string)
: The ID of the secret. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/.

--id (string)
: The ID of the secret version. Required.

The maximum length is 36 characters. The minimum length is 7 characters. The value must match regular expression /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|current|previous)$/.

--locks ([SecretLockPrototype]](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clicli-secret-lock-prototype-example-schema))
: The locks data to be attached to a secret version. Required.
* remove_previous_and_delete: Carries out the same function as remove_previous, but also permanently deletes the data of the previous secret version if it doesn't have any locks.



ibmcloud secrets-manager secret-locks-bulk-create --id ID --locks LOCKS [--mode MODE]



 Command options 

--id (string)
: The ID of the secret. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/.

--locks ([SecretLockPrototype]](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clicli-secret-lock-prototype-example-schema))
: The locks data to be attached to a secret version. Required.

The maximum length is 1000 items. The minimum length is 0 items.

Provide a JSON string option or specify a JSON file to read from by providing a filepath option that begins with a @, e.g. --locks=@path/to/file.json.

--mode (string)
: Set the lock mode. Allowable values: remove_previous, and remove_previous_and_delete. Use remove_previous to create a lock that clears existing locks with matching names. Use remove_previous_and_delete to also delete data from the previous version.

Allowable values are: remove_previous, remove_previous_and_delete.





 Example
created_at 2020-10-05T17:43:49Z
description An updated group of secrets.
id 9c6d20ad-779e-27c5-3842-2a20b19abfcf
name my-updated-secret-group
type application/vnd.ibm.secrets-manager.secret.group+json
updated_at 2020-10-05T17:56:56Z







 Delete a secret group 

Use this command to delete a secret group.

vault delete auth/ibmcloud/manage/groups/SECRET_GROUP_ID



 Prerequisites 

You need the [Manager service role](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam) to delete secret groups.





 Examples 

Delete a secret group by its assigned ID.

vault delete auth/ibmcloud/manage/groups/9c6d20ad-779e-27c5-3842-2a20b19abfcf





 Output 

The command returns the following output:

Success! Data deleted (if it existed) at: auth/ibmcloud/manage/groups/9c6d20ad-779e-27c5-3842-2a20b19abfcf









 Static secrets 



 Create a secret 

Use the following commands to add a static secret, such as a user credential or an arbitrary secret, to your Secrets Manager instance. Allowable values for SECRET_TYPE are: arbitrary,imported_cert, [kv](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-vault-manage-kv-cli), private_cert, public_cert, and username_password.

Create a secret in the default secret group.
{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/private_cert/secrets" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}' -H 'Content-Type: application/json' -d '{
"name": "test-private-certificate",
"description": "Extended description for my secret.",
"certificate_template": "my-configured-certificate-template",
"common_name": "example.com",
"alt_names": [
"www.example.com"
],
"labels": [
"dev",
"us-south"
],
"rotation": {
"auto_rotate": true,
"interval": 90,
"unit": day
}
}'
Show more

Create a private SSL/TLS certificate and assign it to an existing secret group.

curl -X POST "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/private_cert/secrets/groups/{group_id}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}' -H 'Content-Type: application/json' -d '{
"name": "test-private-certificate",
"description": "Extended description for my secret.",
"certificate_template": "my-configured-certificate-template",
"common_name": "example.com",
"alt_names": [
"www.example.com"
],
"labels": [
"dev",
"us-south"
],
"rotation": {
"auto_rotate": true,
"interval": 90,
"unit": day
}
}'
Show more





 Example responses
"not_before": "2021-06-03T15:25:44Z"
}
}
]
},
"wrap_info": null,
"warnings": null,
"auth": null
}







 Get a secret 

Get the value of a secret.



 Example requests 

Get an arbitrary secret.

curl -X GET "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/arbitrary/secrets/{secret_id}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}'

Get an arbitrary secret in an existing secret group.

curl -X GET "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/arbitrary/secrets/groups/{group_id}/{secret_id}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}'

Get IAM credentials.

curl -X GET "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/iam_credentials/creds/{secret_id}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}'

Get IAM credentials in an existing secret group.

curl -X GET "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/iam_credentials/creds/groups/{group_id}/{secret_id}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}'

Get key-value secrets. [Learn more](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-vault-manage-kv&interface=apioverview-kv).
Secrets Manager API change log 

In this change log, you can learn about the latest changes, improvements, and updates for the [IBM Cloud® Secrets Manager API](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2). The change log lists changes that have been made, ordered by the date they were released. Changes to existing API versions are designed to be compatible with existing client applications.

To learn about general updates and improvements to the Secrets Manager service, see [Release notes](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-release-notes).



 17 April 2023 

Version 2.0.0 was released on 17 April 2023. This release includes the following updates:



* You no longer need to include secret_type in the API URL to identify a secret.
* The secret group name must be unique per Secrets Manager instance.
* Resources updates are defined as HTTP patch operations.
* The configurations API follows the pattern of the Secrets Manager API. config_type acts as the API discriminator, similarly to secret_type.
* Configurations are modeled as openAPI composites with metadata and data parts, similarly to the Secrets Manager model. Mappings between IAM roles and configurations API follow the same pattern for the Secrets Manager API. For example, an IAM viewer can list configurations to view their metadata.
* List operations return metadata only for secret, secret version, and config resources.
* The action to rotate a secret is now the create a new secret version API: POST/v2/secrets/{id}/versions.
* The action to restore secret version is now the create a new secret version API with the restored_from_version body parameter.
* The action to delete IAM credentials is now the delete a secret version data API: DELETE /v2/secrets/{id}/versions/{version_id}/secret_data.
* Policies API is now embedded into the metadata API in version 2.0.
* The actions to list Secrets and get secret metadata return the versions_total field. The version's content is not included.
A lock can be used to prevent a secret from being deleted or modified while it's in use by your applications. A successful request attaches a new lock to your secret, or replaces a lock of the same name if it already exists. Additionally, you can use this operation to clear any matching locks on a secret by using one of the following optional lock modes:



* remove_previous: Removes any other locks with matching names if they are found in the previous version of the secret.
* remove_previous_and_delete: Carries out the same function as remove_previous, but also permanently deletes the data of the previous secret version if it doesn't have any locks.



ibmcloud secrets-manager secret-version-locks-bulk-create --secret-id SECRET-ID --id ID --locks LOCKS [--mode MODE]



 Command options 

--secret-id (string)
: The ID of the secret. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/.

--id (string)
: The ID of the secret version. Required.

The maximum length is 36 characters. The minimum length is 7 characters. The value must match regular expression /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|current|previous)$/.

--locks ([SecretLockPrototype]](https://cloud.ibm.com/docs/secrets-manager-cli-plugin?topic=secrets-manager-cli-plugin-secrets-manager-clicli-secret-lock-prototype-example-schema))
: The locks data to be attached to a secret version. Required.