API reference

Secrets Manager API reference

The Secrets Manager API is part of the Thalassa Cloud platform API. Full OpenAPI definitions are available in the API reference.

Base path

/v1/secrets

Required headers

Header	Required	Description
`Authorization`	Yes	Bearer token or equivalent credential
`X-Organisation-Identity`	Yes	Organisation identifier
`X-Project-Identity`	No	Project identifier for project-scoped secrets

Endpoints

Method	Endpoint	Description
`GET`	`/v1/secrets/{region}/secrets?path=/`	Browse one directory level
`GET`	`/v1/secrets/{region}/secrets?pathPrefix=/app/`	Flat list under prefix
`POST`	`/v1/secrets/{region}/secrets`	Create secret + version 1
`GET`	`/v1/secrets/{region}/secret{path}`	Get metadata (`?includeVersions=true`)
`PUT`	`/v1/secrets/{region}/secret{path}/policy`	Set or clear access policy
`POST`	`/v1/secrets/{region}/secret{path}/versions`	Add new version
`POST`	`/v1/secrets/{region}/secret{path}/value`	Reveal value
`DELETE`	`/v1/secrets/{region}/secret{path}/versions?version=N`	Destroy version
`DELETE`	`/v1/secrets/{region}/secret{path}`	Delete secret

Replace {region} with the target cloud region (for example, nl-01). Embed the secret path directly in the URL after /secret.

Path-in-URL examples

GET  /v1/secrets/nl-01/secret/app/production/db/password
POST /v1/secrets/nl-01/secret/app/production/db/password/value
PUT  /v1/secrets/nl-01/secret/app/production/db/password/policy
POST /v1/secrets/nl-01/secret/app/production/db/password/versions
DELETE /v1/secrets/nl-01/secret/app/production/db/password/versions?version=2
DELETE /v1/secrets/nl-01/secret/app/production/db/password

Alternatively, pass the path as a query parameter: ?path=/app/production/db/password.

Regional paths

All secret operations require a region in the path. Secrets exist in exactly one region; cross-region access is not supported.

Common response codes

HTTP status	Meaning
`403`	`secrets` or `kms` feature gate disabled; IAM denied; access policy denied
`404`	Secret, version, or KMS key not found; wrong project scope
`400`	Invalid path; validation error; KMS key disabled; version destroyed; invalid base64 or size limits
`409`	Secret path already exists in org/region/project scope
`503`	KMS not available in the region

See FAQ for troubleshooting.

Documentation by topic

Topic	Guide
Create secrets	Creating secrets
Reveal and rotate	Reading and updating values
Versions	Version management
Access policies	Access policies
IAM	Access control
KMS	KMS integration

Full specification

For request and response schemas, error models, and authentication details, refer to the platform OpenAPI specification in the API reference.

Billing Best practices