Skip to main content

​
The value is a separate endpoint

Describing a secret and reading it are different operations with different permissions.

GET /v1/secrets/{id}

Name, description, tags, current version number, which KMS key it is bound to, deletion state. Never the value. Guarded by secrets:DescribeSecret.

GET /v1/secrets/{id}/value

The decrypted plaintext, base64-encoded. Guarded by the separate, narrower secrets:GetSecretValue.
This split is the point of the service. A deployment tool, a dashboard or an inventory job can be given secrets:DescribeSecret across everything and still be unable to read a single value.
Every plaintext read is recorded, successful or not. A denied read, a probe for an id the caller does not own, and a decrypt that failed are all written to the audit trail with the error code that stopped them — that set is exactly what a review is looking for, and it would be invisible if only successes were logged.
Add ?version=N to read a specific version instead of the current one.
The console’s Reveal button, on each row of a secret’s Versions tab, calls this endpoint. It is the same operation with the same permission and the same audit record — opening a secret in a browser is not a quieter way to read it.

​
Versions

Open the secret from Secrets and choose Put New Value. The Put new value dialog takes the New value; Store new version writes it and it becomes current.Every version stays listed on the Versions tab, with the newest marked Current.
Each call allocates the next version number and makes it current; the previous version stops being current but stays readable by explicit ?version=. That is what makes rotation safe — you publish the new value, let consumers pick it up, and still have the old one to fall back to. GET /v1/secrets/{secret_id}/versions lists version metadata, highest first. Each entry carries created_by, the CRN of the principal that wrote it (crn:iam:::user/<id> or crn:iam:::service-account/<id>), so you can see who rotated what.
Version metadata never includes ciphertext. GET .../value is the only route that produces plaintext, and it is the only one that needs secrets:GetSecretValue.