Getting started

Getting started with Secrets Manager

This guide walks you through the prerequisites for Secrets Manager, creating a KMS encryption key, storing your first secret, and revealing its value.

Prerequisites

Before you begin, ensure the full dependency chain is satisfied:

Requirement	Customer impact
`secrets` feature gate	Must be enabled; otherwise all API calls return `403`
`kms` feature gate	Must be enabled; otherwise calls return `403`
Regional KMS backend	Target region needs an enabled KMS endpoint; otherwise crypto returns `503`
Operational KMS key	A symmetric encryption key (`aes128-gcm96`, `aes256-gcm96`, or `chacha20-poly1305`) must be active
IAM permissions	You need permissions to create secrets and reveal values

All Secrets Manager API requests require:

Authorization — Bearer token or equivalent
X-Organisation-Identity — Your organisation identifier

Optionally include X-Project-Identity to create and manage project-scoped secrets.

If you have not set up KMS yet, follow Getting started with KMS first.

Step 1: Confirm KMS availability

Check that KMS is enabled and available in your target region:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  https://api.thalassa.cloud/v1/kms/summary

Confirm featureEnabled is true and kmsAvailable is true for your region (for example, nl-01).

Step 2: Create a KMS encryption key

Secrets Manager requires a symmetric KMS key in the same region as the secret. Create one if you do not already have a suitable key:

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "secrets-encryption",
    "description": "Encrypts Secrets Manager values",
    "keyType": "aes256-gcm96"
  }' \
  https://api.thalassa.cloud/v1/kms/nl-01/keys

Save the key identity from the response. You bind this key to each secret at creation and cannot change it later.

Step 3: Create a secret

Create a secret at a path with an initial value. Values are base64-encoded on the wire:

SECRET_VALUE=$(echo -n "my-database-password" | base64)

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"path\": \"/app/production/db/password\",
    \"kmsKeyIdentity\": \"$KMS_KEY_IDENTITY\",
    \"description\": \"Production database password\",
    \"secretString\": \"$SECRET_VALUE\"
  }" \
  https://api.thalassa.cloud/v1/secrets/nl-01/secrets

The response returns 201 Created with currentVersion: 1. The secret value is not echoed in the response.

For structured credentials (username and password), use secretKeyValues instead. See Creating secrets.

Step 4: Reveal the secret value

Use getSecretValue to decrypt and return the current version:

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

The response includes:

secretString or secretKeyValues — The decrypted value (base64-encoded for string format)
kmsKeyIdentity — The bound KMS key
kmsKeyVersion — The KMS key version used for decryption

Treat getSecretValue responses as ephemeral. Do not log or persist secret values.

Step 5: Browse secrets

List secrets at a directory level to explore your path hierarchy:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  "https://api.thalassa.cloud/v1/secrets/nl-01/secrets?path=/app/"

The response includes:

prefixes — Child directories containing secrets you can read
secrets — Metadata for secrets stored directly at that path level

Drill down by changing the path query parameter until you reach a leaf secret.

What’s next

Concepts — Paths, versions, value formats, and envelope encryption
Paths and naming — Path rules and naming conventions
Access control — Assign roles for operators, applications, and auditors
Best practices — Security recommendations for production

Creating secrets