Manage secrets

Secrets are managed in the vault's Secrets tab. Changing them needs secretvault/writeSecrets on the vault; revealing a value needs secretvault/readSecrets — see Permissions.

Add a secret

In the Secrets tab choose Add Secret and fill in:

• Name — letters, digits and hyphens, at most 127 characters. It must be unique among the vault's secrets that are not deleted.
• Value — the secret itself. It is encrypted before it is stored.
• Content Type (optional) — a hint for whoever reads it, such as text/plain or application/json.
• Enabled — on by default. A disabled secret cannot be read, by people or workloads.

Choose Create Secret. The value becomes version 1.

Tags and not-before and expiry dates can be set through the API; the portal shows them but does not edit them. An expiry date is informational: the platform still hands out the value after it.

View a secret

The list shows each secret's name, content type, status, current version and when it was last updated. View Details opens the secret: its status, current version, content type, timestamps, expiry and tags, the Secret Value — revealed only when you ask, and recorded in the vault's activity log — and the Versions tab, which lists every version as Active or Inactive. The values of older versions can be read with the CLI or the API.

Change a value

Edit opens the secret with its current value. Saving creates a new version, which becomes current; the previous one becomes inactive but stays readable. The Enabled switch in the same sheet disables the secret, and saving that also creates a new version.

The portal cannot enable a disabled secret again: its row no longer offers Edit. Use the CLI — stsh secret set <name> --stdin -v <vault> stores the value you pass as a new, enabled version — or the API.

Workloads read secrets when their pods start, so a running workload keeps the old value until it restarts — see Use secrets in workloads.

Delete, recover and purge

• Deleting a secret removes it from the list but keeps it, with all its versions. Show Deleted lists deleted secrets again.
• Recovering a deleted secret restores it as it was.
• Purging removes a deleted secret permanently. It is allowed 90 days after the secret was deleted and refused before that. Nothing purges deleted secrets automatically.

This holds whatever the vault's soft-delete, retention and purge-protection settings say; the platform does not apply them yet. Deleting and purging also need secretvault/delete, which the Owner, Contributor and Secrets Writer roles have.

Recover and purge with the CLI:

stsh secret list --vault my-vault
stsh secret recover my-secret --vault my-vault
stsh secret purge my-secret --vault my-vault

Deleting the vault itself removes every secret in it at once, deleted ones included — see Deleting a vault.

Secrets created by a template

A blueprint deploy or a templated container instance can create secrets in its vault. They are marked Template-managed, and their details show the Template, the Origin and, where it applies, what they are Derived from.

• A generated value, such as a password created at deploy time, can be changed after you confirm Change a template-managed secret?. The running service does not follow at once: each component picks up the new value when it next restarts. Some templates do not support changing a generated value at all, and say so.
• A derived value, such as a connection string built from a generated password, cannot be edited. Change the value it is derived from instead.

With the CLI

stsh secret list --vault my-vault
stsh secret set api-key --stdin --vault my-vault     # value from stdin, never in shell history
stsh secret get api-key --vault my-vault --raw
stsh secret get api-key --vault my-vault --version 2
stsh secret versions api-key --vault my-vault
stsh secret delete api-key --vault my-vault

With the API

Each operation is an HTTP call under the vault's secrets path. Setting a value creates a new version:

PUT https://api.example.com/boundaries/<boundary-id>/resourcegroups/my-resource-group/resources/secretvaults/my-vault/secrets/api-key
Content-Type: application/json

{ "value": "example-value", "contentType": "text/plain" }

Reading the value needs secretvault/readSecrets:

GET https://api.example.com/boundaries/<boundary-id>/resourcegroups/my-resource-group/resources/secretvaults/my-vault/secrets/api-key

A Reader sees the secret in the vault's list but is refused its value:

GET https://api.example.com/boundaries/<boundary-id>/resourcegroups/my-resource-group/resources/secretvaults/my-vault/secrets

GET https://api.example.com/boundaries/<boundary-id>/resourcegroups/my-resource-group/resources/secretvaults/my-vault/secrets/api-key