Accessing secrets

After you store secrets in your IBM Cloud® Secrets Manager service instance, you can retrieve their values.

Before you begin

Before you begin, be sure that you have the required level of access. To view a list of your available secrets, you need the Reader service role or higher. To retrieve the value of a secret, you need the SecretsReader service role or higher.

Retrieving a secret in the UI

You can retrieve a secret by using the Secrets Manager UI. Follow these steps to get your secret.

In the Secrets table, click the Actions menu to open a list of options for your secret.
To view the secret value, click View secret.
Click Confirm after you ensure that you are in a safe environment.

The secret value is displayed for 15 seconds, then the dialog closes.

After your secret has been rotated, you can view the previous secret value from the Version history option.

You can also retieve a secret's details such as expiration date, and rotation interval or state.

In the Secrets table, click the Actions menu to open a list of options for your secret.
To view the secret value, click Details.

You can further filter retrieved secrets from the filter option in the Secrets table, and select a secret group and/or secret type.

Downloading certificates

To download a certificate by using the Secrets Manager UI, complete the following steps.

In the console, click the Menu icon > Resource List.
From the list of services, select your instance of Secrets Manager.
In the Secrets table, open the overflow menu for the certificate that you want to download.
Click Download. The certificate file is downloaded to your local system.

Retrieving a secret from the CLI

After you store a secret in your instance, you might need to retrieve its value so that you can connect to an external app or get access to a protected service. You can retrieve the value of a secret by using the Secrets Manager CLI plug-in.

To get the value of a secret as well as review its details such as expiration date and rotation interval or state, run the ibmcloud secrets-manager secret command.

ibmcloud secrets-manager secret --id SECRET_ID

The command outputs the value of the secret, along with other metadata. For more information about the command options, see ibmcloud secrets-manager secret.

You can also get a secret by using its Name:

ibmcloud secrets-manager secret-by-name --secret-type SECRET_TYPE --name SECRET_NAME --secret-group-name SECRET_GROUP_NAME

You can further filter retrieved secrets by using the --secret-types and --match-all-labels optional flags.

Downloading certificates

When you're working with certificates, you might need the ability to download the payload of a certificate into a pem file by using the CLI. To do so, you can use the Secrets Manager CLI plug-in and jq.

To store the certificate into a pem file, run the ibmcloud secrets-manager secret command.

ibmcloud secrets-manager secret --id=SECRET_ID | jq -r '.certificate' | sed 's/\\n/\n/g' > my-cert-file.pem

The command outputs the value of the certificate and stores it to my-cert-file.pem. For more information about the command options, see ibmcloud secrets-manager secret.

Retrieving a secret with the API using secret ID

The following example request retrieves a secret and its details, such as expiration date and rotation interval or state. 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.

You can further filter retrieved secrets by using the ?secret_types and ?match_all_labels optional parameters.

Retrieving a secret with the API using secret Name

You can also retrieve the secret's value by reference its Name instead of ID:

curl -X GET 
    -H "Authorization: Bearer {iam_token}" \
    -H "Accept: application/json" \ 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secret_groups/{secret_group_name}/secret_types/{secret_type}/secrets/{secert_name}"

Note that you need to specify the secret's name, secret group name and secret_type.

You can further filter retrieved secrets by using the ?secret_types and ?match_all_labels optional parameters.

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 additional 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. The following example uses the base64 macOS utility to base64 decode the $ARBITRARY_SECRET contents.

echo $ARBITRARY_SECRET | base64 --decode > my-secret.png

The data is converted back to a binary file that you can open from your local computer.

Downloading the previous version of a certificate

After you rotate a certificate, you can programmatically access its previous version 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  
   --header "Authorization: Bearer {iam_token}" \
   --header "Accept: application/json" \
   "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions/previous"