Create a new secret group
POST /api/v2/secret_groups
Create a secret group that you can use to organize secrets and control who can access them.
A successful request returns the ID value of the secret group, along with other properties. To learn more about secret groups, check out the docs.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-group.create
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-group.create
Request
Request Body
SecretGroupPrototype
The request body to create a new secret group.
name
Required *
string
The name of your secret group.
description
string
An extended description of your secret group.
To protect your privacy, do not use personal data, such as your name or location, as a description for your secret group.
Response
201 - The secret group was successfully created.
id
string
A UUID identifier, or `default` secret group.
name
string
The name of your existing secret group.
description
string
An extended description of your secret group.
To protect your privacy, do not use personal data, such as your name or location, as a description for your secret group.
created_at
string
The date when the resource was created. The date format follows `RFC 3339`.
created_by
string
The unique identifier that is associated with the entity that created the secret.
updated_at
string
The date when a resource was modified. The date format follows `RFC 3339`.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
List secret groups
GET /api/v2/secret_groups
List the secret groups that are available in your Secrets Manager instance.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-groups.list
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-groups.list
Request
Response
200 - The list of secret groups was successfully retrieved.
secret_groups
array
A collection of secret groups.
total_count
integer
The total number of resources in a collection.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
Get a secret group
GET /api/v2/secret_groups/{id}
Get the properties of an existing secret group by specifying the ID of the group.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-group.read
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-group.read
Request
Path Parameters
id
Required *
The UUID that uniquely identifies your secret group.
Query Parameters
Response
200 - The secret group was successfully retrieved.
id
string
A UUID identifier, or `default` secret group.
name
string
The name of your existing secret group.
description
string
An extended description of your secret group.
To protect your privacy, do not use personal data, such as your name or location, as a description for your secret group.
created_at
string
The date when the resource was created. The date format follows `RFC 3339`.
created_by
string
The unique identifier that is associated with the entity that created the secret.
updated_at
string
The date when a resource was modified. The date format follows `RFC 3339`.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
Update a secret group
PATCH /api/v2/secret_groups/{id}
Update the properties of an existing secret group, such as its name or description.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-group.update
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-group.update
Request
Request Body
The request body to update a secret group.
Path Parameters
id
Required *
The UUID that uniquely identifies your secret group.
Query Parameters
Response
200 - The secret group was successfully updated.
id
string
A UUID identifier, or `default` secret group.
name
string
The name of your existing secret group.
description
string
An extended description of your secret group.
To protect your privacy, do not use personal data, such as your name or location, as a description for your secret group.
created_at
string
The date when the resource was created. The date format follows `RFC 3339`.
created_by
string
The unique identifier that is associated with the entity that created the secret.
updated_at
string
The date when a resource was modified. The date format follows `RFC 3339`.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
DELETE /api/v2/secret_groups/{id}
Delete a secret group by specifying the ID of the secret group.
Note: To delete a secret group, it must be empty. If you need to remove a secret group that contains secrets, you must first delete the secrets that are associated with the group.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-group.delete
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-group.delete
Request
Path Parameters
id
Required *
The UUID that uniquely identifies your secret group.
Query Parameters
Response
204 - The secret group was successfully deleted.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
Create a new secret
POST /api/v2/secrets
Create a secret or import an existing value that you can use to access or authenticate to a protected resource.
Use this operation to either generate or import an existing secret, such as a TLS certificate, that you can manage in your Secrets Manager service instance. A successful request stores the secret in your dedicated instance, based on the secret type and data that you specify. The response returns the ID value of the secret, along with other metadata.
To learn more about the types of secrets that you can create with Secrets Manager, check out the docs.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret.create
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret.create
Request
Request Body
SecretPrototype
Response
201 - The secret was successfully created.
400 -
401 -
402 -
403 -
404 -
409 -
422 -
500 -
502 -
503 -
List secrets
GET /api/v2/secrets
List the secrets that are available in your Secrets Manager instance.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secrets.list
Auditing
Calling this method generates the following auditing event.
secrets-manager.secrets.list
Request
Path Parameters
Query Parameters
offset
integer
The number of secrets to skip. By specifying `offset`, you retrieve a subset of items that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.
Usage: If you have 100 secrets in your instance, and you want to retrieve secrets 26 through 50, use `..?offset=25&limit=25`.
limit
integer
The number of secrets to retrieve. By default, list operations return the first 200 items. To retrieve a different set of items, use `limit` with `offset` to page through your available resources. Maximum limit allowed is 1000 secrets.
Usage: If you want to retrieve only the first 25 secrets in your instance, use `..?limit=25`.
sort
string
Sort a collection of secrets by the specified field in ascending order. To sort in descending order use the `-` character
Available values: `id`, `created_at`, `updated_at`, `retrieved_at`, `expiration_date`, `secret_type`, `name`
Usage: To sort a list of secrets by their creation date, use `../secrets?sort=created_at`.
search
string
Obtain a collection of secrets that contain the specified string in one or more of the fields: `id`, `name`, `description`, `labels`, `secret_type`.
Usage: If you want to list only the secrets that contain the string `text`, use `../secrets?search=text`.
groups
array
Filter secrets by groups.
You can apply multiple filters by using a comma-separated list of secret group IDs. If you need to filter secrets that are in the default secret group, use the `default` keyword.
Usage: To retrieve a list of secrets that are associated with an existing secret group or the default group, use `..?groups={secret_group_ID},default`.
secret_types
array
Filter secrets by types.
You can apply multiple filters by using a comma-separated list of secret types.
Usage: To retrieve a list of imported certificates and public certificates use `..?secret_types=imported_cert,public_cert`.
match_all_labels
array
Filter secrets by labels.
You can use a comma-separated list of labels to filter secrets that include all of the labels in the list.
Usage: To retrieve a list of secrets that include both the label "dev" and the label "us-south" in their list of labels, use `..?labels=dev,us-south`.
Response
200 - The list of secrets was successfully retrieved.
total_count
integer
The total number of resources in a collection.
limit
integer
The number of items that are retrieved in a collection.
offset
integer
The number of items that are skipped in a collection.
first
PaginatedCollectionFirst
A URL that points to the first page in a collection.
next
PaginatedCollectionNext
A URL that points to the next page in a collection.
previous
PaginatedCollectionPrevious
A URL that points to the previous page in a collection.
last
PaginatedCollectionLast
A URL that points to the last page in a collection.
secrets
array
A collection of secret metadata.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
GET /api/v2/secrets/{id}
Get a secret and its details by specifying the ID of the secret.
A successful request returns the secret data that is associated with your secret, along with other metadata. To view only the details of a specified secret without retrieving its value, use the Get secret metadata operation.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret.read
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret.read
Request
Response
200 - The secret was successfully retrieved.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
Delete a secret
DELETE /api/v2/secrets/{id}
Delete a secret by specifying the ID of the secret.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret.delete
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret.delete
Request
Path Parameters
Query Parameters
force_delete
boolean
Set to `true` to force delete the secret. Available only for custom credentials secret type.
Response
204 - The secret was successfully deleted.
400 -
401 -
402 -
403 -
404 -
409 -
422 -
500 -
502 -
503 -
Get the metadata of a secret
GET /api/v2/secrets/{id}/metadata
Get the metadata of a secret by specifying the ID of the secret.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-metadata.read
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-metadata.read
Request
Response
200 - The secret metadata was successfully retrieved.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
Update the metadata of a secret
PATCH /api/v2/secrets/{id}/metadata
Update the metadata of a secret, such as its name or description.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-metadata.update
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-metadata.update
Request
Request Body
Response
200 - The secret's metadata was successfully updated.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
Create a secret action
POST /api/v2/secrets/{id}/actions
Create a secret action. This operation supports the following actions:
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-action.create
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-action.create
Request
Request Body
SecretActionPrototype
Response
201 - The secret action was successfully created.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
GET /api/v2/secrets/{secret_id}/tasks
List secret tasks.
Supported secret types: `CUSTOM_CREDENTIALS`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-tasks.list
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-tasks.list
Request
Response
200 - The list of secret tasks was successfully retrieved.
tasks
array
A collection of secret metadata.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
GET /api/v2/secrets/{secret_id}/tasks/{id}
Get a task of a secret and its details by specifying the ID of the task.
A successful request returns the task that is associated with your secret.
Supported secret types: `CUSTOM_CREDENTIALS`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-task.read
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-task.read
Request
Response
200 - The task was successfully retrieved.
id
string
A Secret Manager task identifier.
created_by
string
The unique identifier that is associated with the entity that created the secret.
creation_date
string
The date when the resource was created. The date format follows `RFC 3339`.
last_update_date
string
The date when a resource was modified. The date format follows `RFC 3339`.
updated_by
string
The unique identifier that is associated with the entity that updated the resource.
type
string
The type of the task, can be either "create_credentials" or "delete_credentials"
status
string
The status of a task, could be one of: queued, processing, succeeded, failed.
trigger
string
Information about what has initiated the task.
secret_id
string
A UUID identifier.
secret_version_id
string
A UUID identifier.
errors
SecretTaskErrorCollection
A collection of errors.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
PUT /api/v2/secrets/{secret_id}/tasks/{id}
A callback endpoint for updating a task with results.
Supported secret types: `CUSTOM_CREDENTIALS`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-task.update
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-task.update
Request
Request Body
SecretTaskPrototype
Response
200 - The task was successfully updated.
id
string
A Secret Manager task identifier.
created_by
string
The unique identifier that is associated with the entity that created the secret.
creation_date
string
The date when the resource was created. The date format follows `RFC 3339`.
last_update_date
string
The date when a resource was modified. The date format follows `RFC 3339`.
updated_by
string
The unique identifier that is associated with the entity that updated the resource.
type
string
The type of the task, can be either "create_credentials" or "delete_credentials"
status
string
The status of a task, could be one of: queued, processing, succeeded, failed.
trigger
string
Information about what has initiated the task.
secret_id
string
A UUID identifier.
secret_version_id
string
A UUID identifier.
errors
SecretTaskErrorCollection
A collection of errors.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
DELETE /api/v2/secrets/{secret_id}/tasks/{id}
Delete a task by specifying the ID of the secret.
Supported secret types: `CUSTOM_CREDENTIALS`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-task.delete
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-task.delete
Request
Response
204 - The task was successfully deleted.
400 -
401 -
402 -
403 -
404 -
409 -
422 -
500 -
502 -
503 -
GET /api/v2/secret_groups/{secret_group_name}/secret_types/{secret_type}/secrets/{name}
Get a secret and its details by specifying the name and type of the secret.
A successful request returns the secret data that is associated with your secret, along with other metadata. To view only the details of a specified secret without retrieving its value, use the Get secret metadata operation.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret.read
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret.read
Request
Response
200 - The secret was successfully retrieved.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
501 -
502 -
503 -
Create a new secret version
POST /api/v2/secrets/{secret_id}/versions
Create a new secret version.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-version.create
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-version.create
Request
Request Body
SecretVersionPrototype
payload
Required *
string
The secret data that is assigned to an `ARBITRARY` secret.
custom_metadata
SecretCustomMetadata
The secret metadata that a user can customize.
version_custom_metadata
VersionCustomMetadata
The secret version metadata that a user can customize.
restore_from_version
Required *
string
A UUID identifier, or `current` or `previous` secret version aliases.
certificate
Required *
string
Your PEM-encoded certificate. The data must be formatted on a single line with embedded newline characters.
intermediate
string
The PEM-encoded intermediate certificate that is associated with the root certificate. The data must be formatted on a single line with embedded newline characters.
private_key
string
The PEM-encoded private key that is associated with the certificate. The data must be formatted on a single line with embedded newline characters.
data
Required *
KVSecretPayloadData
The payload data of a key-value secret.
csr
string
The certificate signing request.
rotation
Required *
PublicCertificateRotationObject
Defines the rotation object that is used to manually rotate public certificates.
rotate_keys
boolean
This field indicates whether Secrets Manager rotates the private key for your public certificate automatically.
The default is `false`. If it is set to `true`, the service generates and stores a new private key for your rotated certificate.
password
string
The password that is assigned to an `USERNAME_PASSWORD` secret. If you omit this parameter, Secrets Manager generates a new random password for your secret.
Response
201 - A new secret version was successfully created.
400 -
401 -
402 -
403 -
404 -
409 -
422 -
500 -
502 -
503 -
GET /api/v2/secrets/{secret_id}/versions
List the versions of a secret.
A successful request returns the list of versions of a secret, along with the metadata of each version.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-versions.list
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-versions.list
Request
Response
200 - The list of secret versions was successfully retrieved.
versions
array
A collection of secret version metadata.
total_count
integer
The total number of resources in a collection.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
GET /api/v2/secrets/{secret_id}/versions/{id}
Get a version of a secret by specifying the ID of the version. You can use the `current` or `previous` aliases to refer to the current or previous secret version.
A successful request returns the secret data that is associated with the specified version of your secret, along with other metadata.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-version.read
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-version.read
Request
Response
200 - The secret version was successfully retrieved.
400 -
401 -
402 -
403 -
404 -
410 -
500 -
502 -
503 -
DELETE /api/v2/secrets/{secret_id}/versions/{id}/secret_data
Delete the data of a secret version by specifying its version ID.
This operation is available for the following secret types:
`IAM_CREDENTIALS`: current version only
`CUSTOM_CREDENTIALS`: both current and previous versions
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-version-data.delete
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-version-data.delete
Request
Response
204 - The secret version's data was successfully deleted.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
GET /api/v2/secrets/{secret_id}/versions/{id}/metadata
Get the metadata of a secret version by specifying the ID of the version. You can use the `current` or `previous` aliases to refer to the current or previous secret version.
A successful request returns the metadata that is associated with the specified version of your secret.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-version-metadata.read
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-version-metadata.read
Request
Response
200 - The secret version metadata was successfully retrieved.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
Update the metadata of a secret version
PATCH /api/v2/secrets/{secret_id}/versions/{id}/metadata
Update the custom metadata of a secret version.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-version-metadata.update
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-version-metadata.update
Request
Request Body
Response
200 - The secret version's metadata was successfully updated.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
POST /api/v2/secrets/{secret_id}/versions/{id}/actions
Create a secret version action. This operation supports the following actions:
- `private_cert_action_revoke_certificate`: Revoke a version of a private certificate.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-version-action.create
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-version-action.create
Request
Request Body
SecretVersionActionPrototype
Response
201 - The version action was successfully created.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
List secrets and their locks
GET /api/v2/secrets_locks
List the secrets and their locks in your Secrets Manager instance.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secrets-locks.list
Auditing
Calling this method generates the following auditing event.
secrets-manager.secrets-locks.list
Request
Path Parameters
Query Parameters
offset
integer
The number of secrets to skip. By specifying `offset`, you retrieve a subset of items that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.
Usage: If you have 100 secrets in your instance, and you want to retrieve secrets 26 through 50, use `..?offset=25&limit=25`.
limit
integer
The number of secrets to retrieve. By default, list operations return the first 200 items. To retrieve a different set of items, use `limit` with `offset` to page through your available resources. Maximum limit allowed is 1000 secrets.
Usage: If you want to retrieve only the first 25 secrets in your instance, use `..?limit=25`.
search
string
Filter locks that contain the specified string in the field "name".
Usage: If you want to list only the locks that contain the string "text" in the field "name", use `..?search=text`.
groups
array
Filter secrets by groups.
You can apply multiple filters by using a comma-separated list of secret group IDs. If you need to filter secrets that are in the default secret group, use the `default` keyword.
Usage: To retrieve a list of secrets that are associated with an existing secret group or the default group, use `..?groups={secret_group_ID},default`.
Response
200 - The list of secrets and their locks was successfully retrieved.
total_count
integer
The total number of resources in a collection.
limit
integer
The number of items that are retrieved in a collection.
offset
integer
The number of items that are skipped in a collection.
first
PaginatedCollectionFirst
A URL that points to the first page in a collection.
next
PaginatedCollectionNext
A URL that points to the next page in a collection.
previous
PaginatedCollectionPrevious
A URL that points to the previous page in a collection.
last
PaginatedCollectionLast
A URL that points to the last page in a collection.
secrets_locks
array
A collection of secrets and their locks.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
List secret locks
GET /api/v2/secrets/{id}/locks
List the locks that are associated with a specified secret.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-locks.list
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-locks.list
Request
Path Parameters
Query Parameters
offset
integer
The number of locks to skip. By specifying `offset`, you retrieve a subset of items that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.
Usage: If you have 100 locks on your secret, and you want to retrieve locks 26 through 50, use `..?offset=25&limit=25`.
limit
integer
The number of locks with associated secret to retrieve. By default, list operations return the first 25 items. To retrieve a different set of items, use `limit` with `offset` to page through your available resources.
Usage: If you have 20 secrets in your instance, and you want to retrieve only the first 5, use `..?limit=5`.
sort
string
Sort a collection of locks by the specified field in ascending order. To sort in descending order use the `-` character
Available values: `created_at`, `updated_at`, `name`
Usage: To sort a list of locks by their creation date, use `../locks?sort=created_at`.
search
string
Filter locks that contain the specified string in the field "name".
Usage: If you want to list only the locks that contain the string "text" in the field "name", use `..?search=text`.
Response
200 - The locks were successfully retrieved.
total_count
integer
The total number of resources in a collection.
limit
integer
The number of items that are retrieved in a collection.
offset
integer
The number of items that are skipped in a collection.
first
PaginatedCollectionFirst
A URL that points to the first page in a collection.
next
PaginatedCollectionNext
A URL that points to the next page in a collection.
previous
PaginatedCollectionPrevious
A URL that points to the previous page in a collection.
last
PaginatedCollectionLast
A URL that points to the last page in a collection.
locks
array
A collection of secret locks.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
POST /api/v2/secrets/{id}/locks_bulk
Create a lock 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 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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-locks.create
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-locks.create
Request
Request Body
SecretLockCollectionPrototype
locks
Required *
array
The locks data to be attached to a secret version.
Path Parameters
Query Parameters
mode
An optional lock mode. When you create a lock, you can set one of the following modes to clear any matching locks on a secret version.
- `remove_previous`: Removes any other locks with matching names if they are found in the previous version of the secret. - `remove_previous_and_delete`: Completes the same action as `remove_previous`, but also permanently deletes the data of the previous secret version if it doesn't have any locks. Not supported for custom credentials secret type.
Response
201 - Secret locks were successfully created.
secret_id
string
A UUID identifier.
secret_group_id
string
A UUID identifier, or `default` secret group.
secret_type
string
The secret type. Supported types are arbitrary, imported_cert, public_cert, private_cert, iam_credentials, service_credentials, kv, and username_password.
secret_name
string
The human-readable name of your secret.
versions
array
A collection of locks that are attached to a secret.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
DELETE /api/v2/secrets/{id}/locks_bulk
Delete all the locks or a subset of the locks that are associated with a version of a secret.
To delete only a subset of the locks, add a query param with a comma to separate the list of lock names:
Example: `?name=lock-example-1,lock-example-2`.
Note: A secret is considered unlocked and able to be deleted only after you remove all of its locks. To determine whether a secret contains locks, check the `locks_total` field that is returned as part of the metadata of your secret.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-locks.delete
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-locks.delete
Request
Path Parameters
Query Parameters
name
Specify the names of the secret locks to be deleted.
Response
200 - The locks were deleted successfully.
secret_id
string
A UUID identifier.
secret_group_id
string
A UUID identifier, or `default` secret group.
secret_type
string
The secret type. Supported types are arbitrary, imported_cert, public_cert, private_cert, iam_credentials, service_credentials, kv, and username_password.
secret_name
string
The human-readable name of your secret.
versions
array
A collection of locks that are attached to a secret.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
List secret version locks
GET /api/v2/secrets/{secret_id}/versions/{id}/locks
List the locks that are associated with a specified secret version.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-version-locks.list
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-versions-locks.list
Request
Path Parameters
Query Parameters
offset
integer
The number of locks to skip. By specifying `offset`, you retrieve a subset of items that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.
Usage: If you have 100 locks on your secret, and you want to retrieve locks 26 through 50, use `..?offset=25&limit=25`.
limit
integer
The number of locks with associated secret to retrieve. By default, list operations return the first 25 items. To retrieve a different set of items, use `limit` with `offset` to page through your available resources.
Usage: If you have 20 secrets in your instance, and you want to retrieve only the first 5, use `..?limit=5`.
sort
string
Sort a collection of locks by the specified field in ascending order. To sort in descending order use the `-` character
Available values: `created_at`, `updated_at`, `name`
Usage: To sort a list of locks by their creation date, use `../locks?sort=created_at`.
search
string
Filter locks that contain the specified string in the field "name".
Usage: If you want to list only the locks that contain the string "text" in the field "name", use `..?search=text`.
Response
200 - Locks were successfully retrieved.
total_count
integer
The total number of resources in a collection.
limit
integer
The number of items that are retrieved in a collection.
offset
integer
The number of items that are skipped in a collection.
first
PaginatedCollectionFirst
A URL that points to the first page in a collection.
next
PaginatedCollectionNext
A URL that points to the next page in a collection.
previous
PaginatedCollectionPrevious
A URL that points to the previous page in a collection.
last
PaginatedCollectionLast
A URL that points to the last page in a collection.
locks
array
A collection of secret version locks.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
POST /api/v2/secrets/{secret_id}/versions/{id}/locks_bulk
Create a lock on the specified 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 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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-version-locks.create
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-version-locks.create
Request
Request Body
SecretLockCollectionPrototype
locks
Required *
array
The locks data to be attached to a secret version.
Path Parameters
Query Parameters
mode
An optional lock mode. When you create a lock, you can set one of the following modes to clear any matching locks on a secret version.
- `remove_previous`: Removes any other locks with matching names if they are found in the previous version of the secret. - `remove_previous_and_delete`: Completes the same action as `remove_previous`, but also permanently deletes the data of the previous secret version if it doesn't have any locks. Not supported for custom credentials secret type.
Response
201 - Secret locks were successfully created.
secret_id
string
A UUID identifier.
secret_group_id
string
A UUID identifier, or `default` secret group.
secret_type
string
The secret type. Supported types are arbitrary, imported_cert, public_cert, private_cert, iam_credentials, service_credentials, kv, and username_password.
secret_name
string
The human-readable name of your secret.
versions
array
A collection of locks that are attached to a secret.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
DELETE /api/v2/secrets/{secret_id}/versions/{id}/locks_bulk
Delete all the locks or a subset of the locks that are associated with the specified version of a secret.
To delete only a subset of the locks, add a query param with a comma to separate the list of lock names:
Example: `?name=lock-example-1,lock-example-2`.
Note: A secret is considered unlocked and able to be deleted only after all of its locks are removed. To determine whether a secret contains locks, check the `locks_total` field that is returned as part of the metadata of your secret.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.secret-version-locks.delete
Auditing
Calling this method generates the following auditing event.
secrets-manager.secret-version-locks.delete
Request
Path Parameters
Query Parameters
name
Specify the names of the secret locks to be deleted.
Response
200 - The locks were deleted successfully.
secret_id
string
A UUID identifier.
secret_group_id
string
A UUID identifier, or `default` secret group.
secret_type
string
The secret type. Supported types are arbitrary, imported_cert, public_cert, private_cert, iam_credentials, service_credentials, kv, and username_password.
secret_name
string
The human-readable name of your secret.
versions
array
A collection of locks that are attached to a secret.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
POST /api/v2/configurations
Add a configuration to the specified secret type.
Use this operation to define the configurations that are required to create public certificates (`PUBLIC_CERT`), private certificates (`PRIVATE_CERT`), IAM credentials secrets (`IAM_CREDENTIALS`) and custom credentials secrets (`CUSTOM_CREDENTIALS`).
You can add multiple configurations for your instance as follows:
- A single configuration for IAM credentials.
- Up to 10 CA configurations for public certificates.
- Up to 10 DNS configurations for public certificates.
- Up to 10 Root CA configurations for private certificates.
- Up to 10 Intermediate CA configurations for private certificates.
- Up to 10 Certificate Template configurations for private certificates.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.configuration.create
Auditing
Calling this method generates the following auditing event.
secrets-manager.configuration.create
Request
Request Body
ConfigurationPrototype
Response
201 - The configuration was successfully created.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
List configurations
GET /api/v2/configurations
List the configurations that are available in your Secrets Manager instance.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.configurations.list
Auditing
Calling this method generates the following auditing event.
secrets-manager.configurations.list
Request
Path Parameters
Query Parameters
offset
integer
The number of configurations to skip. By specifying `offset`, you retrieve a subset of items that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.
Usage: If you have 100 configurations in your instance, and you want to retrieve configurations 26 through 50, use `..?offset=25&limit=25`.
limit
integer
The number of configurations to retrieve. By default, list operations return the first 200 items. To retrieve a different set of items, use `limit` with `offset` to page through your available resources. Maximum limit allowed is 1000 secrets.
Usage: If you want to retrieve only the first 25 configurations in your instance, use `..?limit=25`.
sort
string
Sort a collection of configurations by the specified field in ascending order. To sort in descending order use the `-` character
Available values: `config_type`, `secret_type`, `name`
Usage: To sort a list of configurations by their creation date, use `../configurations?sort=config_type`.
search
string
Obtain a collection of configurations that contain the specified string in one or more of the fields: `name`, `config_type`, `secret_type`.
Usage: If you want to list only the configurations that contain the string `text`, use `../configurations?search=text`.
secret_types
array
Filter configurations by secret types: `IAM_CREDENTIALS`, `PUBLIC_CERT`, `PRIVATE_CERT`, or `CUSTOM_CREDENTIALS`.
You can apply multiple filters by using a comma-separated list of secret types.
Usage: To retrieve a list of configurations that are associated with all secret types, use `..?secret_types=IAM_CREDENTIALS,PUBLIC_CERT,PRIVATE_CERT,CUSTOM_CREDENTIALS`.
Response
200 - The list of configurations was successfully retrieved.
total_count
integer
The total number of resources in a collection.
limit
integer
The number of items that are retrieved in a collection.
offset
integer
The number of items that are skipped in a collection.
first
PaginatedCollectionFirst
A URL that points to the first page in a collection.
next
PaginatedCollectionNext
A URL that points to the next page in a collection.
previous
PaginatedCollectionPrevious
A URL that points to the previous page in a collection.
last
PaginatedCollectionLast
A URL that points to the last page in a collection.
configurations
array
A collection of configuration metadata.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
GET /api/v2/configurations/{name}
Get a configuration by specifying its name.
A successful request returns the details of your configuration.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.configuration.read
Auditing
Calling this method generates the following auditing event.
secrets-manager.configuration.read
Request
Response
200 - The configuration was successfully retrieved.
300 -
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
Update configuration
PATCH /api/v2/configurations/{name}
Update a configuration.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.configuration.update
Auditing
Calling this method generates the following auditing event.
secrets-manager.configuration.update
Request
Request Body
Response
200 - The configuration was successfully updated.
300 -
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
Delete a configuration
DELETE /api/v2/configurations/{name}
Delete a configuration by specifying its name.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.configuration.delete
Auditing
Calling this method generates the following auditing event.
secrets-manager.configuration.delete
Request
Response
204 - The configuration was successfully deleted.
300 -
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
POST /api/v2/configurations/{name}/actions
Create a configuration action. This operation supports the following actions:
- `private_cert_configuration_action_sign_intermediate`: Sign an intermediate certificate authority.
- `private_cert_configuration_action_sign_csr`: Sign a certificate signing request.
- `private_cert_configuration_action_set_signed`: Set a signed intermediate certificate authority.
- `private_cert_configuration_action_revoke_ca_certificate`: Revoke an internally signed intermediate certificate authority certificate.
- `private_cert_configuration_action_rotate_crl`: Rotate the certificate revocation list (CRL) of an intermediate certificate authority.
- `private_cert_configuration_action_rotate_intermediate`: Rotate an internally signed intermediate certificate authority certificate.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.configuration-action.create
Auditing
Calling this method generates the following auditing event.
secrets-manager.configuration-action.create
Request
Request Body
ConfigurationActionPrototype
Response
201 - The version action was successfully created.
300 -
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
Register with Event Notifications instance
POST /api/v2/notifications/registration
Create a registration between a Secrets Manager instance and Event Notifications.
A successful request adds Secrets Manager as a source that you can reference from your Event Notifications instance. For more information about enabling notifications for Secrets Manager, check out the docs.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.notifications-registration.create
Auditing
Calling this method generates the following auditing event.
secrets-manager.notifications-registration.create
Request
Request Body
NotificationsRegistrationPrototype
event_notifications_instance_crn
Required *
string
A CRN that uniquely identifies an IBM Cloud resource.
event_notifications_source_name
Required *
string
The name that is displayed as a source that is in your Event Notifications instance.
event_notifications_source_description
string
An optional description for the source that is in your Event Notifications instance.
Response
201 - The notification registration was successfully created.
event_notifications_instance_crn
string
A CRN that uniquely identifies an IBM Cloud resource.
400 -
401 -
402 -
403 -
404 -
409 -
500 -
502 -
503 -
Get Event Notifications registration details
GET /api/v2/notifications/registration
Get the details of the registration between your Secrets Manager instance and Event Notifications.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.notifications-registration.read
Auditing
Calling this method generates the following auditing event.
secrets-manager.notifications-registration.read
Request
Response
200 - The registration details were successfully retrieved.
event_notifications_instance_crn
string
A CRN that uniquely identifies an IBM Cloud resource.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
DELETE /api/v2/notifications/registration
Delete the registration between your Secrets Manager instance and Event Notifications.
A successful request removes your Secrets Manager instance as a source in Event Notifications.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.notifications-registration.delete
Auditing
Calling this method generates the following auditing event.
secrets-manager.notifications-registration.delete
Request
Response
204 - The registration was successfully deleted.
400 -
401 -
402 -
403 -
404 -
500 -
502 -
503 -
Send a test event for Event Notifications registrations
GET /api/v2/notifications/registration/test
Send a test event from a Secrets Manager instance to a configured Event Notifications instance.
A successful request sends a test event to the Event Notifications instance. For more information about enabling notifications for Secrets Manager, check out the docs.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
secrets-manager.notifications-registration.test
Auditing
Calling this method generates the following auditing event.
secrets-manager.notifications-registration.test