Creating secrets

Create a secret with POST /v1/secrets/{region}/secrets. The request creates the secret container and version 1 in a single operation.

Required fields

Field	Description
`path`	Secret identity (see Paths and naming)
`kmsKeyIdentity`	Regional symmetric KMS key for encryption

Provide exactly one value input (see below).

Value input options

Input	Use case
`secretString`	Base64-encoded single value
`secretKeyValues`	Map of named base64 values (for example, username + password)
`generateSecret`	Platform generates random bytes and encrypts them

String value

For a single blob such as an API token, PEM certificate, or connection string:

SECRET_VALUE=$(echo -n "sk_live_abc123" | base64)

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

Key/value pairs

For structured credentials with multiple fields:

USERNAME=$(echo -n "dbadmin" | base64)
PASSWORD=$(echo -n "s3cur3-p@ss" | 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/credentials\",
    \"kmsKeyIdentity\": \"$KMS_KEY_IDENTITY\",
    \"secretKeyValues\": {
      \"username\": \"$USERNAME\",
      \"password\": \"$PASSWORD\"
    }
  }" \
  https://api.thalassa.cloud/v1/secrets/nl-01/secrets

Platform-generated secret

Let the platform generate cryptographically random bytes. Prefer this for passwords and tokens rather than accepting user-typed secrets in a browser:

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/app/production/api/webhook-secret",
    "kmsKeyIdentity": "'"$KMS_KEY_IDENTITY"'",
    "generateSecret": { "byteLength": 32 }
  }' \
  https://api.thalassa.cloud/v1/secrets/nl-01/secrets

byteLength must be between 16 and 4096.

Optional fields

Field	Description
`description`	Human-readable description
`labels`	Key-value labels
`annotations`	Additional metadata
`accessPolicy`	IP and time restrictions (see Access policies)

KMS key selection

Bind a symmetric KMS key that:

Exists in the same region as the secret
Is active (not disabled or pending deletion)
Supports encryption (aes128-gcm96, aes256-gcm96, or chacha20-poly1305)

The KMS key binding is immutable. Choose your key carefully at creation. See KMS integration.

Create a dedicated key per environment or sensitivity tier — for example, separate keys for production and staging secrets.

Response

A successful create returns 201 Created with currentVersion: 1. The secret value is not echoed in the response. Follow up with getSecretValue if you need to confirm the stored value (for example, after generateSecret).

Permissions

Creating a secret at a path requires create permission on that exact path. See Access control.

Size limits

Constraint	Limit
Single string (`secretString`)	1–4096 decoded bytes (base64 on wire)
Generated secret (`byteLength`)	16–4096 bytes
Key/value: keys per version	Up to 256
Key/value: key name	1–128 chars, `[A-Za-z0-9_.-]`
Key/value: each value	1–4096 decoded bytes (base64 on wire)
Key/value: total decoded size	≤ 65,536 bytes across all keys

See FAQ for troubleshooting validation errors.