Reading and updating

Reading and updating secret values

This page covers revealing secret values and adding new versions to rotate credentials.

Reveal a secret value

Use POST /v1/secrets/{region}/secret{path}/value to decrypt and return a secret value. This operation requires the getSecretValue IAM permission on the path.

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  https://api.thalassa.cloud/v1/secrets/nl-01/secret/app/production/db/password/value

Read a specific version

Omit version to read the current version. Specify version to read a historical revision:

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"version": 2}' \
  https://api.thalassa.cloud/v1/secrets/nl-01/secret/app/production/db/password/value

Response fields

Field	Description
`secretString` or `secretKeyValues`	Decrypted value (base64-encoded for string format)
`kmsKeyIdentity`	The bound KMS key
`kmsKeyVersion`	The KMS key version used for decryption
`version`	The secret version read

Security considerations

getSecretValue is a sensitive operation:

Treat responses as ephemeral — do not log or persist secret values
Applications should read secrets at runtime and hold them in memory only as long as needed
Optional access policies can restrict reveal operations by IP or time of day

Successful reveals update lastAccessedAt on the secret and the version.

Add a new version (rotate)

Use POST /v1/secrets/{region}/secret{path}/versions to store a new value. This increments currentVersion and moves the current stage to the new revision. Previous versions remain readable until destroyed.

NEW_VALUE=$(echo -n "new-database-password" | base64)

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d "{\"secretString\": \"$NEW_VALUE\"}" \
  https://api.thalassa.cloud/v1/secrets/nl-01/secret/app/production/db/password/versions

The same value input options apply as at create time: secretString, secretKeyValues, or generateSecret. Provide exactly one.

putSecretValue does not change the bound KMS key or path.

Rotation workflow

Add a new version with putSecretValue
Update dependent applications to use the new value
Verify applications are healthy
Destroy superseded versions to limit exposure and stop version storage billing

See Version management for destroying old versions.

Access policy enforcement

If an access policy is configured, it is evaluated after IAM on both getSecretValue and putSecretValue. Metadata operations are not gated by the policy.

KMS key state

If the bound KMS key is disabled or pending deletion, getSecretValue and putSecretValue return 400 Bad Request. Metadata APIs continue to work. See KMS integration.

Base64 encoding

All values are base64-encoded in API requests and responses. Application developers must decode secretString and each entry in secretKeyValues before use:

import base64

secret_string = base64.b64decode(response["secretString"]).decode("utf-8")