Skip to content
Documentation
Key Management Service
Getting started

Getting started with KMS

This guide walks you through checking KMS availability in your organisation, creating a symmetric encryption key, and encrypting and decrypting a small payload.

Prerequisites

Before you begin, ensure you have:

  • KMS enabled — KMS must be enabled for your organisation
  • Regional availability — KMS must be available in the target region
  • IAM permissions — You need permissions to create and use KMS keys. The kms:FullAccess policy includes full lifecycle access; see Access control for other policies
  • API access — A valid access token and organisation identity for API calls

All KMS 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 keys.

Step 1: Check availability

Use the KMS summary endpoint to confirm 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

The response includes:

  • featureEnabled — Whether KMS is enabled for your organisation
  • Per-region kmsAvailable — Whether KMS is available in each region
  • Per-region key counts — How many keys exist in each region

If featureEnabled is false, contact your platform administrator to enable KMS. If kmsAvailable is false for a region, choose a different region or contact support.

Step 2: Create an encryption key

Create an AES-256-GCM key in your target region. This is the recommended default for volume encryption, secrets, and envelope encryption:

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

Save the key identity or slug from the response. You need it for subsequent crypto operations.

Key metadata (name, description, labels) is set at creation and cannot be changed later. Choose names carefully.

Step 3: Encrypt data

Encrypt a small payload. Plaintext must be base64-encoded and between 1 and 65,535 bytes after decoding:

PLAINTEXT=$(echo -n "hello, kms" | base64)

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d "{\"plaintext\": \"$PLAINTEXT\"}" \
  https://api.thalassa.cloud/v1/kms/nl-01/keys/app-encryption/encrypt

The response includes:

  • ciphertext — Encrypted data in Thalassa format (thalassa:vN:…)
  • keyVersion — The key version used for encryption

Store the ciphertext. The embedded version lets KMS decrypt data even after key rotation.

Step 4: Decrypt data

Decrypt the ciphertext using the same key and region:

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d "{\"ciphertext\": \"$CIPHERTEXT\"}" \
  https://api.thalassa.cloud/v1/kms/nl-01/keys/app-encryption/decrypt

The response includes base64-encoded plaintext and the keyVersion used for decryption.

Production pattern: envelope encryption

For production workloads, do not send large files or bulk data through the encrypt API. Instead:

  1. Generate a data encryption key (DEK) in your application
  2. Encrypt your data locally with the DEK
  3. Use KMS to encrypt (wrap) the DEK
  4. Store the wrapped DEK alongside the encrypted data
  5. On read, unwrap the DEK with KMS and decrypt data locally

See Encrypt and decrypt for limits, ciphertext format, and envelope encryption guidance.

What’s next

  • Key types — Choose algorithms for encryption, signing, or HMAC
  • Creating keys — Rotation, export settings, and labels at create time
  • Access control — Assign roles for administrators, operators, and auditors
  • Best practices — Security recommendations for production
Key types