Quickstart

This quickstart uses the CLI so every step is copyable. Run it from a directory linked to your Alien project.

1. Enable Encryption Gateway

alien projects capabilities enable encryption

alien api-keys create \
  --for encryption-gateway \
  --description local-quickstart

The secret is shown once. Save it with the customer ID you will use for this test:

export ALIEN_ENCRYPTION_API_KEY="..."
export CUSTOMER_ID="org_123"

2. Connect your test key

alien onboard "Test customer" \
  --external-id "$CUSTOMER_ID" \
  --setup-items keys

Open the returned link and connect a key from an AWS, Google Cloud, or Azure account you control.

3. Encrypt one value

The CLI can print the request for the active Alien environment:

alien examples encryption-gateway \
  --operation encrypt \
  --key-id customer-data

Run the printed command. The API accepts base64 and returns base64; aGVsbG8= is hello.

curl "https://encryption.alien.dev/v1/encrypt" \
  -H "Authorization: Bearer $ALIEN_ENCRYPTION_API_KEY" \
  -H "X-Alien-External-ID: $CUSTOMER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "key": {"keyId": "customer-data"},
    "plaintext": "aGVsbG8="
  }'

Save the returned ciphertext:

export CIPHERTEXT="..."

4. Decrypt it

alien examples encryption-gateway \
  --operation decrypt \
  --key-id customer-data

The printed request uses ALIEN_ENCRYPTION_API_KEY, CUSTOMER_ID, and CIPHERTEXT. The response contains the plaintext as base64.

5. Test disabled access

Disable the test key in the customer cloud, wait longer than the five-minute root cache, then try decrypt again. The reload through the customer KMS should fail. Restore access and verify that decrypt works again.

Search request diagnostics if the result is unexpected:

alien logs --source encryption-gateway \
  --operation decrypt \
  --since 1h

Only after this test should you decide how your product behaves while the customer key is unavailable.