Secret Manager API documentationv1alpha1

Download OpenAPI

Introduction

Scaleway’s Secret Manager allows you to conveniently store, access and share sensitive data such as passwords, API keys and certificates. With Secret Manager you can manage secrets which are logical containers made up of zero or more immutable versions, that hold sensitive data. Your data is encrypted both in transit and at rest and it is automatically replicated to multiple zones within your region of choice.

Concepts

Refer to our dedicated concepts page to find definitions of the different terms referring to Secret Manager.

Quickstart

Requirements: To perform the following steps, you must first ensure that:

1. Configure your environment variables.

Note: This is an optional step that seeks to simplify your usage of the Secret Manager API.

2. Create a secret. Run the following command to create a secret:

3. Create a secret version. Run the following command to create a version of your secret:

4. Access data from your latest secret version. Run the following command to access the data of your most recent secret version:

Note: Requests can either target a specific version or the latest.

Limitations

  • Operations on secrets and versions are limited to CRUDL
  • A secret's payload size is limited to 64KiB

Going further

For more information about Secret Manager, you can check out the following pages:

Secrets

Secrets are logical containers made up of zero or more immutable versions, that contain sensitive data.

List secrets

Retrieve the list of secrets created within an Organization and/or Project. You must specify either the organization_id or the project_id and the region.

GET
/secret-manager/v1alpha1/regions/{region}/secrets
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Query Parameters
organization_id
string
Filter by Organization ID (optional). (UUID format).
project_id
string
Filter by Project ID (optional). (UUID format).
name
string
Filter by secret name (optional).
tags
array
List of tags to filter on (optional).
order_by
string
Possible values are name_asc, name_desc, created_at_asc, created_at_desc, updated_at_asc and updated_at_desc. The default value is name_asc.
page
integer
Page number. The default value is 1.
page_size
integer
Page size. The default value is 20.
200 Response
total_count
integer
Count of all secrets matching the requested criteria.
secrets
array
Single page of secrets matching the requested criteria.
Response Example

Create a secret

You must sepcify the region to create a secret.

POST
/secret-manager/v1alpha1/regions/{region}/secrets
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Body
project_id
string
ID of the Project containing the secret. (UUID format).
name
string
Name of the secret.
tags
array
List of the secret's tags.
description
nullable string
Description of the secret.
Request Example
200 Response
id
string
ID of the secret. (UUID format).
project_id
string
ID of the Project containing the secret. (UUID format).
name
string
Name of the secret.
status
string
Current status of the secret. * `ready`: the secret is ready. * `locked`: the secret is locked. Possible values are ready and locked. The default value is ready.
created_at
nullable string
Date and time of the secret's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the secret. (RFC 3339 format).
tags
array
List of the secret's tags.
region
string
Region of the secret.
version_count
integer
Number of versions for this secret.
description
nullable string
Updated description of the secret.
Response Example

Get metadata using the secret's ID

Retrieve the metadata of a secret specified by the region and the secret_id parameters.

GET
/secret-manager/v1alpha1/regions/{region}/secrets-by-name/{secret_name}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_name
required string
Name of the secret.
200 Response
id
string
ID of the secret. (UUID format).
project_id
string
ID of the Project containing the secret. (UUID format).
name
string
Name of the secret.
status
string
Current status of the secret. * `ready`: the secret is ready. * `locked`: the secret is locked. Possible values are ready and locked. The default value is ready.
created_at
nullable string
Date and time of the secret's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the secret. (RFC 3339 format).
tags
array
List of the secret's tags.
region
string
Region of the secret.
version_count
integer
Number of versions for this secret.
description
nullable string
Updated description of the secret.
Response Example

Get metadata using the secret's name

Retrieve the metadata of a secret specified by the region and the secret_name parameters.

GET
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
200 Response
id
string
ID of the secret. (UUID format).
project_id
string
ID of the Project containing the secret. (UUID format).
name
string
Name of the secret.
status
string
Current status of the secret. * `ready`: the secret is ready. * `locked`: the secret is locked. Possible values are ready and locked. The default value is ready.
created_at
nullable string
Date and time of the secret's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the secret. (RFC 3339 format).
tags
array
List of the secret's tags.
region
string
Region of the secret.
version_count
integer
Number of versions for this secret.
description
nullable string
Updated description of the secret.
Response Example

Update metadata of a secret

Edit a secret's metadata such as name, tag(s) and description. The secret to update is specified by the secret_id and region parameters.

PATCH
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
Body
name
nullable string
Secret's updated name (optional).
tags
nullable array
Secret's updated list of tags (optional).
description
nullable string
Description of the secret.
Request Example
200 Response
id
string
ID of the secret. (UUID format).
project_id
string
ID of the Project containing the secret. (UUID format).
name
string
Name of the secret.
status
string
Current status of the secret. * `ready`: the secret is ready. * `locked`: the secret is locked. Possible values are ready and locked. The default value is ready.
created_at
nullable string
Date and time of the secret's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the secret. (RFC 3339 format).
tags
array
List of the secret's tags.
region
string
Region of the secret.
version_count
integer
Number of versions for this secret.
description
nullable string
Updated description of the secret.
Response Example

Delete a secret

Delete a given secret specified by the region and secret_id parameters.

DELETE
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
204 Response
Empty response

Secret versions

Versions store the sensitive data contained in your secrets (API keys, passwords, or certificates).

List versions of a secret using the secret's name

Retrieve the list of a given secret's versions specified by the secret_name and region parameters.

GET
/secret-manager/v1alpha1/regions/{region}/secrets-by-name/{secret_name}/versions
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_name
required string
Name of the secret.
Query Parameters
page
integer
Page number. The default value is 1.
page_size
integer
Page size. The default value is 20.
status
array
Filter results by status.
200 Response
total_count
integer
Number of versions.
versions
array
Single page of versions.
Response Example

Get metadata of a secret's version using the secret's name

Retrieve the metadata of a secret's given version specified by the region, secret_name and revision parameters.

GET
/secret-manager/v1alpha1/regions/{region}/secrets-by-name/{secret_name}/versions/{revision}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_name
required string
Name of the secret.
revision
required string
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1. Value can be a number or "latest".
200 Response
secret_id
string
ID of the secret. (UUID format).
revision
integer
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1.
status
string
Current status of the version. * `unknown`: the version is in an invalid state. * `enabled`: the version is accessible. * `disabled`: the version is not accessible but can be enabled. * `destroyed`: the version is permanently deleted. It is not possible to recover it. Possible values are unknown, enabled, disabled and destroyed. The default value is unknown.
created_at
nullable string
Date and time of the version's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the version. (RFC 3339 format).
description
nullable string
Description of the version.
Response Example

Access a secret's version using the secret's name

Access sensitive data in a secret's version specified by the region, secret_name and revision parameters.

GET
/secret-manager/v1alpha1/regions/{region}/secrets-by-name/{secret_name}/versions/{revision}/access
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_name
required string
Name of the secret.
revision
required string
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1. Value can be a number or "latest".
200 Response
secret_id
string
ID of the secret. (UUID format).
revision
integer
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1.
data
string
The base64-encoded secret payload of the version.
Response Example

List versions of a secret using the secret's ID

Retrieve the list of a given secret's versions specified by the secret_id and region parameters.

GET
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}/versions
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
Query Parameters
page
integer
Page number. The default value is 1.
page_size
integer
Page size. The default value is 20.
status
array
Filter results by status.
200 Response
total_count
integer
Number of versions.
versions
array
Single page of versions.
Response Example

Create a version

Create a version of a given secret specified by the region and secret_id parameters.

POST
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}/versions
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
Body
data
string
The base64-encoded secret payload of the version.
description
nullable string
Description of the version.
Request Example
200 Response
secret_id
string
ID of the secret. (UUID format).
revision
integer
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1.
status
string
Current status of the version. * `unknown`: the version is in an invalid state. * `enabled`: the version is accessible. * `disabled`: the version is not accessible but can be enabled. * `destroyed`: the version is permanently deleted. It is not possible to recover it. Possible values are unknown, enabled, disabled and destroyed. The default value is unknown.
created_at
nullable string
Date and time of the version's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the version. (RFC 3339 format).
description
nullable string
Description of the version.
Response Example

Get metadata of a secret's version using the secret's ID

Retrieve the metadata of a secret's given version specified by the region, secret_id and revision parameters.

GET
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}/versions/{revision}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
revision
required string
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1. Value can be a number or "latest".
200 Response
secret_id
string
ID of the secret. (UUID format).
revision
integer
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1.
status
string
Current status of the version. * `unknown`: the version is in an invalid state. * `enabled`: the version is accessible. * `disabled`: the version is not accessible but can be enabled. * `destroyed`: the version is permanently deleted. It is not possible to recover it. Possible values are unknown, enabled, disabled and destroyed. The default value is unknown.
created_at
nullable string
Date and time of the version's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the version. (RFC 3339 format).
description
nullable string
Description of the version.
Response Example

Update metadata of a version

Edit the metadata of a secret's given version, specified by the region, secret_id and revision parameters.

PATCH
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}/versions/{revision}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
revision
required string
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1. Value can be a number or "latest".
Body
description
nullable string
Description of the version.
Request Example
200 Response
secret_id
string
ID of the secret. (UUID format).
revision
integer
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1.
status
string
Current status of the version. * `unknown`: the version is in an invalid state. * `enabled`: the version is accessible. * `disabled`: the version is not accessible but can be enabled. * `destroyed`: the version is permanently deleted. It is not possible to recover it. Possible values are unknown, enabled, disabled and destroyed. The default value is unknown.
created_at
nullable string
Date and time of the version's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the version. (RFC 3339 format).
description
nullable string
Description of the version.
Response Example

Access a secret's version using the secret's ID

Access sensitive data in a secret's version specified by the region, secret_id and revision parameters.

GET
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}/versions/{revision}/access
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
revision
required string
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1. Value can be a number or "latest".
200 Response
secret_id
string
ID of the secret. (UUID format).
revision
integer
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1.
data
string
The base64-encoded secret payload of the version.
Response Example

Delete a version

Delete a secret's version and the sensitive data contained in it. Deleting a version is permanent and cannot be undone.

POST
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}/versions/{revision}/destroy
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
revision
required string
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1. Value can be a number or "latest".
Body
Request Example
200 Response
secret_id
string
ID of the secret. (UUID format).
revision
integer
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1.
status
string
Current status of the version. * `unknown`: the version is in an invalid state. * `enabled`: the version is accessible. * `disabled`: the version is not accessible but can be enabled. * `destroyed`: the version is permanently deleted. It is not possible to recover it. Possible values are unknown, enabled, disabled and destroyed. The default value is unknown.
created_at
nullable string
Date and time of the version's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the version. (RFC 3339 format).
description
nullable string
Description of the version.
Response Example

Disable a version

Make a specific version inaccessible. You must specify the region, secret_id and revision parameters.

POST
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}/versions/{revision}/disable
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
revision
required string
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1. Value can be a number or "latest".
Body
Request Example
200 Response
secret_id
string
ID of the secret. (UUID format).
revision
integer
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1.
status
string
Current status of the version. * `unknown`: the version is in an invalid state. * `enabled`: the version is accessible. * `disabled`: the version is not accessible but can be enabled. * `destroyed`: the version is permanently deleted. It is not possible to recover it. Possible values are unknown, enabled, disabled and destroyed. The default value is unknown.
created_at
nullable string
Date and time of the version's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the version. (RFC 3339 format).
description
nullable string
Description of the version.
Response Example

Enable a version

Make a specific version accessible. You must specify the region, secret_id and revision parameters.

POST
/secret-manager/v1alpha1/regions/{region}/secrets/{secret_id}/versions/{revision}/enable
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
secret_id
required string
ID of the secret. (UUID format).
revision
required string
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1. Value can be a number or "latest".
Body
Request Example
200 Response
secret_id
string
ID of the secret. (UUID format).
revision
integer
Version number. The first version of the secret is numbered 1, and all subsequent revisions augment by 1.
status
string
Current status of the version. * `unknown`: the version is in an invalid state. * `enabled`: the version is accessible. * `disabled`: the version is not accessible but can be enabled. * `destroyed`: the version is permanently deleted. It is not possible to recover it. Possible values are unknown, enabled, disabled and destroyed. The default value is unknown.
created_at
nullable string
Date and time of the version's creation. (RFC 3339 format).
updated_at
nullable string
Last update of the version. (RFC 3339 format).
description
nullable string
Description of the version.
Response Example