secret.md

Documentation for scw secret

This API allows you to manage your Secret Manager services, for storing, accessing and sharing sensitive data such as passwords, API keys and certificates.

Secret management commands

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

Allow a product to use the secret

Allow a product to use the secret.

Usage:

scw secret secret add-owner <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
product	ID of the product to add	One of: unknown_product, edge_services, s2s_vpn
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Create a secret

Create a secret in a given region specified by the region parameter.

Usage:

scw secret secret create [arg=value ...]

Arguments:

Name	Description	Argument Specifications
project-id	Project ID to use. If none is passed the default project ID will be used
name	Name of the secret
tags.{index}	List of the secret's tags
description	Description of the secret
type	Type of the secret	One of: unknown_type, opaque, certificate, key_value, basic_credentials, database_credentials, ssh_key
path	Path of the secret
ephemeral-policy.time-to-live	Time frame, from one second and up to one year, during which the secret's versions are valid.
ephemeral-policy.expires-once-accessed	Returns true if the version expires after a single user access.
ephemeral-policy.action	Action to perform when the version of a secret expires	One of: unknown_action, delete, disable
protected	Returns true if secret protection is applied to a given secret
key-id	ID of the Scaleway Key Manager key
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Examples:

Create a given secret

scw secret secret create name=foobar description="$(cat <path/to/your/secret>)"

Delete a secret

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

Usage:

scw secret secret delete <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Examples:

Delete a given secret

scw secret secret delete 11111111-1111-1111-1111-111111111111

Get metadata using the secret's ID

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

Usage:

scw secret secret get <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

List secrets

Retrieve the list of secrets created within an Organization and/or Project. If the user has permissions for all current and future projects: Either organization_id or project_id is required. If the user has permissions for all current projects or only specific projects: The project_id is required. The region parameter in path is needed in both case.

Usage:

scw secret secret list [arg=value ...]

Arguments:

Name	Description	Argument Specifications
project-id	Filter by Project ID (optional)
order-by		One of: name_asc, name_desc, created_at_asc, created_at_desc, updated_at_asc, updated_at_desc
tags.{index}	List of tags to filter on (optional)
name	Filter by secret name (optional)
path	Filter by exact path (optional)
ephemeral	Filter by ephemeral / not ephemeral (optional)
type	Filter by secret type (optional)	One of: unknown_type, opaque, certificate, key_value, basic_credentials, database_credentials, ssh_key
scheduled-for-deletion	Filter by whether the secret was scheduled for deletion / not scheduled for deletion. By default, it will display only not scheduled for deletion secrets.
organization-id	Filter by Organization ID (optional)
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw, all

Enable secret protection

Enable secret protection for a given secret specified by the secret_id parameter. Enabling secret protection means that your secret can be read and modified, but it cannot be deleted.

Usage:

scw secret secret protect <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret to enable secret protection for	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Examples:

Enable secret protection

scw secret secret protect 11111111-1111-1111-1111-111111111111

Disable secret protection

Disable secret protection for a given secret specified by the secret_id parameter. Disabling secret protection means that your secret can be read, modified and deleted.

Usage:

scw secret secret unprotect <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret to disable secret protection for	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Examples:

Disable secret protection

scw secret secret unprotect 11111111-1111-1111-1111-111111111111

Update metadata of a secret

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

Usage:

scw secret secret update <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
name	Secret's updated name (optional)
tags.{index}	Secret's updated list of tags (optional)
description	Description of the secret
path	Path of the folder
ephemeral-policy.time-to-live	Time frame, from one second and up to one year, during which the secret's versions are valid.
ephemeral-policy.expires-once-accessed	Returns true if the version expires after a single user access.
ephemeral-policy.action	Action to perform when the version of a secret expires	One of: unknown_action, delete, disable
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Secret Version management commands

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

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.

Usage:

scw secret version access <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
revision	Version number	Required
field	Return only the JSON field of the given name
raw	Return only the raw payload
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Examples:

Get a raw json value from a secret version

scw secret version access 11111111-1111-1111-111111111111 revision=1 field=key raw=true

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

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

Usage:

scw secret version access-by-path [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-path	Secret's path
secret-name	Secret's name
revision	Version number	Required
project-id	Project ID to use. If none is passed the default project ID will be used
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Create a version

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

Usage:

scw secret version create <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
data	Content of the secret version.	Required
description	Description of the version
disable-previous	Disable the previous secret version
data-crc32	(Optional.) The CRC32 checksum of the data as a base-10 integer
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Examples:

Create a json secret version

scw secret version create 11111111-1111-1111-111111111111 data={"key":"value"}

Delete a version

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

Usage:

scw secret version delete <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
revision	Version number	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Examples:

Delete a given Secret Version

scw secret version delete 11111111-1111-1111-1111-111111111111 revision=1

Disable a version

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

Usage:

scw secret version disable <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
revision	Version number	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

Enable a version

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

Usage:

scw secret version enable <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
revision	Version number	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

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.

Usage:

scw secret version get <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
revision	Version number	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw

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.

Usage:

scw secret version list <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
status.{index}	Filter results by status	One of: unknown_status, enabled, disabled, deleted, scheduled_for_deletion
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw, all

Update metadata of a version

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

Usage:

scw secret version update <secret-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
secret-id	ID of the secret	Required
revision	Version number	Required
description	Description of the version
ephemeral-properties.expires-at	The version's expiration date
ephemeral-properties.expires-once-accessed	Returns true if the version expires after a single user access.
ephemeral-properties.action	Action to perform when the version of a secret expires	One of: unknown_action, delete, disable
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, nl-ams, pl-waw