Quick Start: Enable Encryption

Enable encryption for your FreeState organization in 3 simple steps. All new workspaces will automatically encrypt state data at rest with AES-256-GCM.

Step 1: Navigate to Organization Settings

1. Log in to the FreeState Portal
2. Select your organization from the top-left dropdown
3. Click Settings in the left sidebar, then select the Encryption tab

Step 2: Enable Encryption

1. Click the Enable Encryption button
2. Review the encryption overview in the confirmation modal
3. Check the acknowledgement: “I understand that encrypted workspaces cannot be decrypted without access to the encryption keys”
4. Click Enable

Processing takes 2–5 seconds. FreeState generates a master Key Encryption Key (KEK) in AWS KMS and stores the configuration.

Step 3: Verify Encryption Status

After enabling, confirm the following in the Encryption settings:

• Encryption status badge shows Enabled (green)
• Key type shows FreeState-Managed
• New workspaces will display a 🔒 icon in the workspace list

Verify via API

curl -H "Authorization: Bearer $TOKEN" \
  https://api.freestate.cloud/api/v1/organizations/$ORG_ID/encryption/status

# Expected response:
{
  "organization_id": "11111111-2222-3333-4444-555555555555",
  "encryption_enabled": true,
  "byok_enabled": false,
  "kms_provider": "aws-kms",
  "key_type": "managed",
  "kek_id": "arn:aws:kms:us-east-1:123456789012:key/abcd-ef01-2345-6789-abcdEF012345",
  "encryption_enabled_at": "2026-01-03T12:00:00Z"
}

How It Works Behind the Scenes

1. KEK Creation: FreeState generates a master Key Encryption Key (KEK) in AWS KMS
2. DEK Generation: Each new workspace automatically gets a unique Data Encryption Key (DEK) on its first state write
3. Encryption: The DEK encrypts state data using AES-256-GCM; the KEK encrypts the DEK
4. Storage: The encrypted DEK is stored in the database; encrypted state is written to object storage

Performance Impact

• Encryption overhead: <10ms per state operation (DEK cached after first use)
• New workspaces: Automatically encrypted — no action required
• Existing workspaces: Encrypted on next state write

Next Steps