Secrets Manager API change log

11 March 2024

• The service endpoints API now also returns the key management service selected for the service instance - provider-managed, or user-provided (Key Protect or Hyper Protect Crypto Services).
• The List secrets API now accepts additional parameters, ?secret_types=... to filter by secret type, and ?match_all_labels=... to filter by a label or a combination of labels.

12 February 2024

• The User credentials secret type now supports generating a random password on secret creation if the password field is kept empty. In addition you can control the password's length, and whether to include numbers, symbols and upper-case letters by including the password_generation_policy field. To learn more, see Storing user credentials.
• For an existing DNS Provider configuration, you can switch between API key and service-to-service authorization by passing an empty string in the apikey field. Note: it is assumed that a service-to-service authorization to the same Cloud Internet Services instance with an identical or matching access policy was configured prior to the switch.

20 September 2023

Get a secret by name instead of ID by using a new API endpoint /api/v2/secret_groups/{secret_group_name}/secret_types/{secret_type}/secrets/{name}. Learn more in Accessing secrets.

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.
• 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 method that can be used to store version custom metadata that is relevant to the needs of your organization.
• Updated the Create a secret, Invoke an action on a secret, Get secret metadata, Get secret version metadata, and Update secret metadata methods to include custom_metadata and version_custom_metadata fields.

10 July 2022

This release includes the following updates:

• Added the Lock a secret and Lock a secret version methods that can be used to create locks on a secret in your instance. For more information, see Locking secrets.
• Added the Unlock a secret and Unlock a secret version methods that can be used to remove locks on a secret or specific secret version.
• Added the List secret locks, List secret version locks, and List all secrets and locks.
• Updated all secrets operations to return a locks_total field as part of the metadata of a secret.

25 April 2022

This release includes the following updates:

• Added the private_cert secret type that can be used to generate TLS certificates with the service. For more information, see Creating private certificates.
• Added the Invoke an action on a version of a secret method that can be used to revoke a version of a private certificate. Currently, this API supports private_cert secrets only.
• Updated the Invoke an action on a secret method to include revoke as a supported action. Currently, the revoke action is supported for private_cert secrets only.
• Updated the Get a version of a secret method that can be used to retrieve the previous version of a secret. This API now supports private_cert secrets in addition to imported_cert and public_cert.
• Updated the Add a configuration, List configurations, Update a configuration, Get a configuration, and Remove a configuration methods. These APIs now support private_cert secrets in addition to public_cert.
• Added the Invoke an action on a configuration method that be used to run operations on specific configuration elements, for example root or intermediate certificate authorities. Currently, this API supports private_cert secrets only.

3 February 2022

This release includes the following update:

• Added the Register with Event Notifications, Get Event Notifications registration details, Unregister from Event Notifications, and Send test event methods that can be used to manage your connection to the Event Notifications service.

31 January 2022

This release includes the following update:

• Added kv as a secret type to the Create a secret method. You can store and manage key-value secrets, including complex JSON documents, that are used to access protected systems that are inside or outside of IBM Cloud.

22 November 2021

This release includes the following updates:

• Added the service_id string parameter as a request body option to the Create a secret method. You can use this field to create IAM credentials with an existing service ID from your account, so that only an API key is generated when the secret is read or accessed.
• Added the api_key_id string parameter to the response details of the Create a secret and Get secret metadata methods.
• Added the service_id_is_static boolean parameter to the response details of the Create a secret and Get secret metadata methods. This parameter indicates whether an IAM credential secret was created by using an existing service ID.
• Added the List versions of a secret method that can be used to obtain version history information for a secret.
• Added payload_available and downloaded boolean parameters to the response details of the Get a secret, Get secret version metadata, List versions of a secret methods. These parameters can help you to identify whether the a secret version is available to be restored, and whether it has already been previously read or accessed.
• Added the restore query parameter as a request option on the Invoke an action on a secret method. You can use this action to restore the previous version of a secret.
• Updated the Get a version of a secret method that can be used to retrieve the previous version of a secret. This API now supports arbitrary, iam_credentials, and username_password secrets, in addition to public_cert and imported_cert.

20 September 2021

This release includes the following updates:

• Added public_cert secret type that can be used to order domain-validated TLS certificates with the service. For more information, see Ordering certificates.
• Added the Add a configuration, List configurations, Update a configuration, Get a configuration, and Remove a configuration methods that can be used to add engine configurations to the service. Currently, these APIs support public_cert secrets only.
• Updated the Get a version of a secret method that can be used to retrieve the previous version of a secret. This API now supports public_cert secrets in addition to imported_cert.

11 July 2021

This release includes the following updates:

• Changed the maximum length for secret names to 240 characters.
• Changed the maximum length for secret descriptions to 1024 characters.

20 June 2021

This release includes the following updates:

• Added imported_cert secret type that can be used to store X.509 certificates in the service. For more information, see Importing certificates.
• Added the Get a version of a secret method that can be used to retrieve the previous version of a secret. Currently, this API supports imported_cert secrets only.

13 April 2021

This release includes the following updates:

• Added group={secret_group_ID} query parameter that can be used to filter a list of secrets by secret group.

7 March 2021

This release includes the following updates:

• Added the reuse_api_key boolean parameter for IAM credential secrets.

10 February 2021

This release includes the following updates:

• Added the search={string} query parameter that can be used to filter a list of secrets that contain a specified string.
• Added the sort_by={field_name} query parameter that can be used to filter a list of secrets by a specified metadata field.

25 January 2021

This release includes the following updates:

• Changed the maximum length for secret names to 128 characters.
• Changed the maximum length for secret group names to 62 characters.