vania-janet/multiturn-rag-retrieval-data huggingface dataset:
You can retrieve the value of a secret by using the Secrets Manager API.

The following example request retrieves a secret and its contents. 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 GET
-H "Authorization: Bearer {iam_token}" -H "Accept: application/json" 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{secret_ID}"

A successful response returns the value of the secret, along with other metadata. For more information about the required and optional request parameters, see [Get a secret](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-secret).



 Retrieving arbitrary secrets that contain binary data 

If you created an arbitrary secret by using a binary file, such as an image, the service uses base64 encoding to store the data as a base64 encoded string. To access the secret in its original form, you need to complete a few extra steps to base64 decode your retrieved secret.

First, retrieve the secret by calling the Secrets Manager API. The following example uses cURL and jq to collect the payload value of a secret.

export ARBITRARY_SECRET=curl -X GET
-H "Authorization: Bearer $IAM_TOKEN" -H "Accept: application/json"
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/arbitrary/{id}" | jq --raw-output '.payload | sub(".,"; "")'

If you inspect the contents of $ARBITRARY_SECRET, you see base64 encoded data. The following snippet shows an example output.

echo $ARBITRARY_SECRET
eUdB68klDSrzSKgWcQS5...(truncated)

To view the secret in its original form (binary file), you can use base64 decoding.
* UI
* CLI
* API
* Terraform







 Storing user credentials 

You can use IBM Cloud® Secrets Manager to store a username and password that you can use to log in to and access a protected service inside or outside of IBM Cloud.

User credentials consist of username and password values that you can use to log in to or access an external service or application. Your secret is stored securely in your dedicated Secrets Manager service instance. In the instance, you can centrally manage its lifecycle, and control the secret's lifespan by setting an expiration date, automatic rotation policies, and more.

To learn more about the types of secrets that you can manage in Secrets Manager, see [What is a secret?](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-what-is-secret)



 Before you begin 

Before you get started, be sure that you have the required level of access. To create or add secrets, you need the [Writer service role or higher](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam).





 Adding user credentials in the UI 

To store a username and password by using the Secrets Manager UI, complete the following steps.



1. In the console, click the Menu icon ![Menu icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/icon_hamburger.svg)> Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets table, click Add.
4. From the list of secret types, select the User credentials tile.
5. Click Next.
6. Add a name and description to easily identify your secret.
7. Select the

secret groupthat you want to assign to the secret.

Don't have a secret group?
* 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.
* Current and previous secret versions can be referenced by using the current and previous aliases in version APIs.
* As of April 17, 2023, the IBM Cloud® Secrets Manager API v1 has been deprecated in favor of v2. If you're still actively working with the Secrets Manager API v1, please be sure to start your upgrade as soon as possible. On 31 October 2023, support for the Secrets Manager API v1 will be removed.







 12 September 2022 

This release includes the following updates:



* Added the [Update the metadata of a secret version](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2update-secret-version-metadata) method that can be used to store version custom metadata that is relevant to the needs of your organization.
"secret_type": "arbitrary",
...
"secret_data": {
"payload": "The quick brown fox jumped over the lazy dog."
}
}

If you're working with IAM credentials, the secret data is listed alongside the other common fields that describe your secret. For example, the following truncated example shows how secret data is represented for an IAM credential.

{
"name": "my-iam-credentials",
"secret_type": "iam_credentials",
...
"api_key": "RmnPBn6n1dzoo0v3kyznKEpg0WzdTpW9lW7FtKa017_u",
"api_key_id": "ApiKey-dcd0b857-b590-4507-8c64-ae89a23e8d76",
"service_id": "ServiceId-bb4ccc31-bd31-493a-bb58-52ec399800be",
}







 How do I get started? 

To get started with secrets, you can go to the Secrets page of the Secrets Manager UI, or check out the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2) to learn more about creating secrets programmatically.
ibmcloud secrets-manager secret-version-locks --secret-id=0b5571f7-21e6-42b7-91c5-3f5ac9793a46 --id=eb4cf24d-9cae-424b-945e-159788a5f535 --offset=0 --limit=10 --sort=name --search=example





 Example output 

Example response for listing secret version locks

{
"first" : {
"href" : "https://us-south.secrets-maanger.cloud.ibm.com/88b75b20-aa21-4174-85c9-1feb3cc93c9a/api/v2/secrets/0cf4addb-7a90-410b-a3a7-a15bbe2b7909/versions/7bf3814d-58f8-4df8-9cbd-f6860e4ca973/locks?limit=50"
},
"previous" : {
"href" : "https://us-south.secrets-maanger.cloud.ibm.com/88b75b20-aa21-4174-85c9-1feb3cc93c9a/api/v2/secrets/0cf4addb-7a90-410b-a3a7-a15bbe2b7909/versions/7bf3814d-58f8-4df8-9cbd-f6860e4ca973/locks?offset=50&limit=50"
},
"last" : {
"crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/791f5fb10986423e97aa8512f18b7e65:e415e570-f073-423a-abdc-55de9b58f54e:secret:285d83ce-4a26-c5c3-8e58-48d3140a2415",
"id": "285d83ce-4a26-c5c3-8e58-48d3140a2415",
"labels": ],
"last_update_date": "2020-10-06T03:54:26Z",
"name": "another-test-arbitrary-secret",
"secret_group_id": "9ab2250f-a369-4e07-ade7-d417d63ad587",
"secret_type": "ARBITRARY",
"state": 1,
"state_description": "Active"
}
],
"secrets_total": 2
},
"warnings": null
}

If the secrets belong to a secret group, the data.secrets.secret_group_id value is included in the response to identify the secret group assignment.







 Get a secret 

Use the following commands to retrieve a secret and its details. Allowable values for SECRET_TYPE are: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, and username_password.

Get a secret.

vault read [-format=FORMAT] ibmcloud/SECRET_TYPE/secrets/SECRET_ID

Get a secret that is assigned to a specified secret group.

vault read [-format=FORMAT] ibmcloud/SECRET_TYPE/secrets/groups/SECRET_GROUP_ID/SECRET_ID



 Prerequisites
The resolved value of a by CRN or by name secret reference is never exposed to the front-end and is always dynamically resolved at runtime within a toolchain and pipeline based on a permitted [authorization](https://cloud.ibm.com/iam/authorizations) being available (configured using IAM Authorizations and Access Policies).

Within IBM Cloud®, the dynamic process of resolving by CRN and by name secrets references in toolchains and pipelines is performed using internal virtual private endpoints (VPE) to all IBM Cloud® Secrets Manager and IBM® Key Protect provider instances in all regions. This ensures all request and response data between toolchains, pipelines, and IBM Cloud® Secrets Manager and IBM® Key Protect provider instances is kept within the in-boundary private IBM Cloud network and does not travel over any public network channels.

In addition to manually selecting chosen secrets on a one-by-one basis from any bound secrets integrations in a toolchain, the option of using a Secret Hint is also available. This option enables a toolchain template to be predefined with suggested secrets names (also known as Hints) that are a short form secret reference. The format of a secret hint is {vault::secret-name} whereby no secret integration name is included. This provides flexibility to the toolchain author in that all required secret names can be prepopulated into a toolchain.yml and then these names are automatically resolved against whatever secrets integrations are configured for the toolchain.

As previously described, you can configure Secrets Manager to reference secrets by CRN. For more information, see [Cloud Resource Names (CRN)](https://cloud.ibm.com/docs/account?topic=account-crn). This format allows for greater flexibility because you can reference secrets from an Secrets Manager instance in a different account if the correct [authorization](https://cloud.ibm.com/iam/authorizations) is in place. For more information see [Configuring Secrets Manager](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-secretsmanager).

The secrets that are used in both CI and CD are outlined as follows:
Values of the version_custom_metadata are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

Secrets Manager supports text-based payloads only for arbitrary secrets. If you need to upload a binary file, you must base64 encode the data first so that you can pass it to the Secrets Manager API in a single-line string. To access this secret later in its original form, you need to base64 decode it. Consider assigning a label on your secret with encoded data, such as encode:base64, so that you can track secrets that require base64 decoding.

curl -X POST
-H "Authorization: Bearer {iam_token}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
"custom_metadata": {
"metadata_custom_key": "metadata_custom_value"
},
"description": "Description of my arbitrary secret.",
"expiration_date": "2023-10-05T11:49:42Z",
"labels": [
"dev",
"us-south"
],
"name": "example-arbitrary-secret",
"payload": "secret-data",
"secret_group_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
"secret_type": "arbitrary",
"version_custom_metadata": {
"custom_version_key": "custom_version_value"} }' 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets"

A successful response returns the ID value of the secret, along with other metadata.
Check whether DevSecOps Toolchain passes static code scan to identify vulnerabilities in source code CM-3(2)(0), CM-4(0), CM-4(1)(0), CM-7(1)(a), CM-7(b), RA-5(1)(0), RA-5(2)(0), RA-5(3)(0), RA-5(a), RA-5(b), RA-5(c), RA-5(d), SA-10(e), SA-15(a), SA-3(a), SA-3(d), SA-8(0), SI-10(0), SI-2(2)(0), SI-2(a), SI-2(b), SI-2(c), and SI-2(d) Rule was added 
 Check whether DevSecOps Toolchain passes dynamic code scan to identify vulnerabilities in deployed artifacts CM-3(2)(0), CM-4(0), CM-4(1)(0), CM-7(1)(a), CM-7(b), RA-5(1)(0), RA-5(2)(0), RA-5(3)(0), RA-5(a), RA-5(b), RA-5(c), RA-5(d), SA-10(e), SA-15(a), SA-3(a), SA-3(d), SA-8(0), SI-10(0), SI-2(2)(0), SI-2(a), SI-2(b), SI-2(c), and SI-2(d) Rule was added 
 Check whether Secrets Manager arbitrary secrets are rotated at least every # days IA-5(g) Rule was added 
 Check whether Secrets Manager user credentials are rotated at least every # days IA-5(g) Rule was added
Secrets Manager sends the request to the configured certificate authority (CA), for example Let's Encrypt, to validate the ownership of your domains. If the validation completes successfully, a new certificate is issued. 
 [User credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-user-credentials) Passwords that are associated with user credentials secrets are immediately replaced with the data that you provide on rotation. 









 Creating new secret versions in the UI 

You can manually rotate your secrets and certificates by using the Secrets Manager UI.



 Rotating arbitrary secrets 

You can use the Secrets Manager UI to manually rotate your arbitrary secrets.



1. In the console, click the Menu icon ![Menu icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/icon_hamburger.svg)> Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets Manager UI, go to the Secrets list.
4. In the row for the secret that you want to rotate, click the Actions menu ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/actions-icon-vertical.svg)> Rotate.
5. Select a new file or enter a new secret value.
6. Optional: Add metadata to your secret or to a specific version of your secret.



1. Upload a file or enter the metadata and the version metadata in JSON format.



7. To rotate the secret immediately, click Rotate.
8. Optional: Check the version history to view the latest updates.

In the row of the secret that you rotated, click the Actions menu !
An account administrator (or any entity with the required level of access) can externally alter IAM Credentials that are created and managed by Secrets Manager. If such a service ID or API key is deleted outside of Secrets Manager, the service might behave unexpectedly. For example, you might be unable to create, or rotate credentials.





 Creating IAM credentials in the UI 

To create IAM credentials by using the Secrets Manager UI, complete the following steps.



1. In the console, click the Menu icon ![Menu icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/icon_hamburger.svg)> Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets table, click Add.
4. From the list of secret types, click the IAM credentials tile.
5. Click Next.
6. Add a name and description to easily identify your secret.
7. Select the

secret groupthat you want to assign to the secret.

Don't have a secret group? In the Secret group field, you can click Create to provide a name and a description for a new group. Your secret is added to the new group automatically. For more information about secret groups, check out [Organizing your secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secret-groups).
8. Optional: Add labels to help you to search for similar secrets in your instance.
9. Optional: Add metadata to your secret or to a specific version of your secret.



1. Upload a file or enter the metadata and the version metadata in JSON format.



10. Click Next.
11. Set a lease duration or time-to-live (TTL) for the secret.

By setting a lease duration for your IAM credential, you determine how long its associated API key remains valid.
* UI
* CLI
* API







 Automatically rotating secrets 

You can schedule automatic rotation for secrets by using IBM Cloud® Secrets Manager.

When you rotate a secret in your service instance, you create a new version of its value. By scheduling automatic rotation of your secrets at regular intervals, you can reduce the likelihood of compromise and ensure that your credentials never expire.

Automatic rotation is available only for secrets that are generated by Secrets Manager. If the secret was imported initially, you must provide new secret data to rotate it. For more information, see [Manually rotating secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-manual-rotation).



 Before you begin 

Before you get started, be sure that you have the required level of access. To rotate secrets, you need the [Writer service role or higher](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam).



 Supported secret types 

Automatic rotation is supported for [private certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-certificatescreate-certificates), [public certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-certificatesorder-certificates), [user credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-user-credentials) and [IAM credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials). Depending on the type of secret, automatic rotation takes place immediately on the date and time that you set, or it might need to complete a few extra steps before a new version of the secret can be created.



Table 1. Describes how Secrets Manager evaluates manual rotation by secret type

 Type Rotation description 

 [Private certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-certificatescreate-certificates) The existing certificate value is replaced with new certificate content.
Secrets Manager works with IAM to generate a new API Key for an IAM credentials secret and manages the versioning of the secret.

The IAM credentials secret type also helps to provide continuity of service during and after secret rotation:



* New Continuous Delivery pipeline workloads use the newly rotated API Key until its lease duration expires.
* Existing Continuous Delivery pipeline workloads that are running with the API Key that was issued before rotation can continue to run with the previous version until the lease duration of the previous version expires.



Zoom

![IAM credentials secret rotation](https://cloud.ibm.com/docs-content/v1/content/562806c0b18119f4d21cb66f5ae6d051634b4a16/ContinuousDelivery/images/secret-iamcredentials-rotation.png)

Figure 4. IAM credentials secret rotation

For more information about the IAM credentials secret type in Secrets Manager, see [Creating IAM credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials).





 Using key-value secrets 

You can select the key-value secrets to use in your toolchain by selecting an individual key from the key-value secret in the Secrets dialog. Alternatively, you can select the secret in its entirety.



1. Click the key icon to retrieve secrets from secure stores such as Secrets Manager for the IBM Cloud API key.
2. In the Provider field, specify the provider and the name of the Secrets Manager tool integration that you use to manage your toolchain secrets. For example, to use the Secrets Manager tool integration, select Secrets Manager: ibm-secrets-manager-1. You can use other providers to manage your toolchain secrets, such as [HashiCorp Vault](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-hashicorpvault) and [Key Protect](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-keyprotect).
3.
"secret_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
"secret_name": "example-arbitrary-secret",
"secret_type": "arbitrary",
"version_custom_metadata": {
"custom_version_key": "custom_version_value"
}
}

The downloaded property indicates whether the data for each secret version was already read or accessed. If the payload_available field has a value of true, it means that you're able to access or [restore the secret data of that version](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history&interface=uirestore-secret-api).

You can store metadata that is relevant to the needs of your organization with the version_custom_metadata request parameter. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data. For more information about the required and optional request parameters, check out the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2)





 Restoring secrets to a previous version 

Accidentally replace or overwrite an existing secret? You can use IBM Cloud® Secrets Manager to immediately roll back to the previous version.

When you restore a secret to its previous version, a new version of the secret is created. For example, if the current version of your secret is 3, and you roll back to version 2, the data that was restored from version 2 becomes version 4.

You can restore one version back on [supported secret types](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-automatic-rotation&interface=uibefore-auto-rotate-supported-secret-types). For auditing purposes, the service retains the metadata of up to 50 versions for each secret, which you can review as part of a secret's [version history](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history).
"secret_version_alias": "previous",
"secret_version_id": "09d9718b-b411-4111-a8f4-b1397d22d11b"
}
],
"locks_total": 2
},
"wrap_info": null,
"warnings": null,
"auth": null
}
Show more







 Lock a secret 

[Create one or more locks](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secret-locks) on the current version of a secret.

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 method to clear any matching locks on a secret by using an optional lock mode.



* lock_exclusive: Removes any other locks with matching names if they are found in the previous version of the secret.
* lock_exclusive_delete: Same as lock_exclusive, but also permanently deletes the data of the previous secret version if no locks are found.





Table 9. Lock secret request parameters

 Request parameters Description 

 name A human-readable name to assign to your secret lock. Names are unique per secret version. /n Note: Creating a lock with an existing name replaces the lock and overrides its attributes. 
 description An extended description of your secret lock. 
 attributes Optional information to associate with a lock, such as resources CRNs to be used by automation. 





 Example request 

Create a lock on a secret in the default secret group.

curl -X POST "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/{secret_type}/locks/{secret_id}/lock" -H 'X-Vault-Token: {Vault-Token}'
-H 'Content-Type: application/json' -D '{
"locks": [
{