Concepts

Secrets Manager concepts

This page explains the core concepts behind Secrets Manager: how secrets are identified, scoped, versioned, and encrypted.

Secret (container)

A secret is a container identified by its path. Each secret is scoped to:

Scope	Required	Description
Organisation	Yes	Your Thalassa Cloud organisation
Cloud region	Yes	Exactly one region per secret
Project	No	Set via `X-Project-Identity` or OIDC project claim

At creation, you bind exactly one KMS key (kmsKeyIdentity). This binding is immutable — you cannot change the encryption key after create.

Metadata

Secret metadata includes:

Field	Description
`description`	Human-readable description
`labels`	Key-value labels for organisation and filtering
`annotations`	Additional metadata
`currentVersion`	The latest active version number
`lastAccessedAt`	Updated when a value is successfully decrypted
`accessPolicy`	Optional IP and time restrictions

Secret values are never returned on list or metadata APIs.

Version (revision)

Each stored value is a numbered version:

Event	Version behaviour
Create secret	Version 1 is created
`putSecretValue`	Increments version (2, 3, …)
Latest active version	Marked with stage `current`
`destroySecretVersion`	Version status becomes `destroyed`; value cannot be read

Destroyed versions remain in version history for audit purposes but are not decryptable.

Retrieve version history (without values) with GET /v1/secrets/{region}/secret{path}?includeVersions=true.

Value formats

Each version stores exactly one payload format:

Format	Write with	Read returns	Use case
`string`	`secretString` (base64) or `generateSecret`	`secretString` (base64)	Single blob: API token, PEM, connection string
`keyValue`	`secretKeyValues` (map of base64 values)	`secretKeyValues` (map of base64 values)	Structured credentials: username + password

Use key/value for credentials with multiple fields. Use string for a single value.

Envelope encryption

Secret material is encrypted with KMS before storage:

You provide plaintext (or request platform generation)
Secrets Manager encrypts the value with the bound KMS key
The encrypted envelope (ciphertext + KMS key identity + KMS key version) is stored internally
On getSecretValue, the value is decrypted and returned

The encrypted envelope is never exposed on metadata APIs. On successful getSecretValue, the response includes kmsKeyIdentity and kmsKeyVersion for transparency, but not the raw ciphertext.

Each getSecretValue and putSecretValue triggers underlying KMS decrypt and encrypt operations, visible in the audit log.

Last accessed

lastAccessedAt on the secret and per version is updated when a value is successfully decrypted via getSecretValue. Use this field for access reviews and identifying unused secrets.

Scoping model

Regional

Secrets exist in exactly one cloud region. All API calls use /v1/secrets/{region}/…. Cross-region secret access is not supported.

Project context

Context	Scope
With `X-Project-Identity`	Secrets are project-scoped
Without project context	Secrets are organisation-scoped

This follows the same pattern as KMS keys, VPCs, and NAT gateways. List, get, and mutations only apply within the active scope.

Path namespace

Paths form a hierarchical namespace, similar to a filesystem:

/
├── app/
│   ├── production/
│   │   └── db/
│   │       ├── password
│   │       └── credentials
│   └── staging/
│       └── db/
│           └── password
└── infra/
    └── vpn/
        └── cert

Paths are the IAM resource identity. Two secrets cannot share the same path within the same organisation + region + project scope.