Integrate with your product

Add Encryption Gateway to your product as a BYOK integration:

your settings page → customer connects a cloud key → your backend encrypts their data

The customer can use AWS KMS, Google Cloud KMS, or Azure Key Vault. Alien gets the access needed to use the key; your application never receives the customer's cloud credentials or raw key material.

1. Choose an external ID

An externalId is your stable identifier for a customer or tenant, such as org_123. Use the same value when you create their setup link and when you encrypt or decrypt data for them.

Use an immutable database ID, not a display name or a value supplied by the browser. Resolve it from the authenticated customer on your backend.

2. Enable Encryption Gateway

Enable key setup for the project and create a gateway key for encrypt and decrypt requests:

alien projects capabilities enable encryption

alien api-keys create \
  --for encryption-gateway \
  --description production

Save the returned secret as ALIEN_ENCRYPTION_KEY.

3. Add a Connect key button

When the customer opens your BYOK settings, create a setup link on your backend and redirect them to deploymentLink.

import { Alien } from "@alienplatform/platform-api"

const alien = new Alien({ apiKey: process.env.ALIEN_API_KEY })

const setup = await alien.setupLinks.create({
  project: "my-project",
  externalId: customer.id,
  name: customer.slug,
  setupItems: [{ item: "keys", required: true }],
})

return setup.deploymentLink

Calling this endpoint again with the same project and externalId reuses the customer record and returns a fresh link. Create links when the customer clicks Connect or Reconnect, not while rendering the page.

Open a specific cloud

For a generic Connect key button, omit entryPoint and let the customer choose. For a cloud-specific button, add:

{
  "entryPoint": {"item": "keys", "provider": "aws"}
}

The customer can still go back and choose another supported cloud. To make the link AWS-only, also add:

{
  "deploymentSetupConfig": {
    "policy": {"allowedPlatforms": ["aws"]}
  },
  "entryPoint": {"item": "keys", "provider": "aws"}
}

Omit deploymentSetupConfig for the normal flow. See Setup Links API for advanced restrictions.

4. Encrypt customer data

After setup completes, send the same external ID in X-Alien-External-ID. The API accepts and returns base64; aGVsbG8= is hello.

const encrypted = await fetch("https://encryption.alien.dev/v1/encrypt", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ALIEN_ENCRYPTION_KEY}`,
    "X-Alien-External-ID": customer.id,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    key: { keyId: "customer-data" },
    plaintext: Buffer.from("hello").toString("base64"),
  }),
}).then(response => response.json())

keyId names a cryptographic context within the customer connection. Use different values such as documents, credentials, or customer-data when those values should be cryptographically separated.

The REST equivalent is:

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

Store the returned ciphertext with the externalId and keyId needed to decrypt it.

5. Decrypt customer data

Send the ciphertext back with the same external ID and key ID:

curl --fail-with-body \
  "https://encryption.alien.dev/v1/decrypt" \
  -H "Authorization: Bearer $ALIEN_ENCRYPTION_KEY" \
  -H "X-Alien-External-ID: org_123" \
  -H "Content-Type: application/json" \
  -d '{
    "key": {"keyId": "customer-data"},
    "ciphertext": "'$CIPHERTEXT'"
  }'

The response contains the plaintext as base64. See the Encryption Gateway quickstart for a complete command-line test.

6. Show connection status

Use the capability overview to render the customer's BYOK status:

const overview = await alien.projects.getCapabilityOverview({
  idOrName: "my-project",
})

const group = overview.groups.find(
  group => group.externalId === customer.id,
)

const keys = group?.capabilities.keys

Use keys.state as the top-level UI state:

To reconnect or change clouds, create another setup link with the same externalId. If the customer disables or deletes their cloud key, encrypt and decrypt fail after any cached key material expires. Continue reading the overview until the UI reflects the new state.

Choose how to use the key

The examples above use the Encrypt/Decrypt API, which is best for fields, documents, credentials, and other data your application stores itself.

To protect Aurora, S3, DynamoDB, or EBS without sending plaintext through the Encrypt/Decrypt API, use an AWS Virtual Key. Your AWS resource sees a normal KMS key while your customer controls the key material behind it.

Test the complete flow

For every cloud you offer:

1. connect a key from an account you control and confirm the state reaches connected;
2. encrypt a value and decrypt the returned ciphertext;
3. disable access to the cloud key and wait longer than the five-minute root cache;
4. confirm decrypt fails and your UI reports that the connection needs attention; and
5. restore access and confirm decrypt succeeds again.

Tell customers what disabling or deleting their key does. Your application can retain ciphertext, but permanently losing the key can make that ciphertext unrecoverable.

Inspect aggregate usage with:

alien usage encryption --range 24h
alien usage encryption --range 30d --json