Customer setup

The setup link is where a customer connects the AWS KMS, Google Cloud KMS, or Azure Key Vault key used for their data.

For a manual test, enable the capability and create a link from the CLI:

alien projects capabilities enable encryption

alien onboard "Acme" \
  --external-id org_123 \
  --setup-items keys

In your product, create the setup link from your backend when the customer opens your BYOK settings.

The example below creates an AWS setup link containing the project’s Encryption Gateway key setup. Use a server-side Alien Platform API key—not the key used to call Encryption Gateway.

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

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

const setup = await alien.setupLinks.create({
  workspace: "my-workspace",
  createSetupLinkRequest: {
    project: "my-project",
    externalId: customer.id,
    name: customer.slug,
    deploymentSetupConfig: {
      metadata: { label: `${customer.name} encryption` },
      policy: {
        allowedPlatforms: ["aws"],
        allowedSetupMethods: ["cloudformation"],
      },
      environmentVariables: [],
    },
    setupItems: [{ item: "keys", required: true }],
    inputValues: {},
  },
})

return setup.deploymentLink

For Google Cloud or Azure, configure the link in the dashboard first and mirror its reviewed setup policy in your backend. See the exact Setup Links API.

Use the same stable customer ID your backend will send with every Encrypt/Decrypt request.

The customer chooses AWS KMS, Google Cloud KMS, or Azure Key Vault and completes the provider-specific setup. Alien receives the access needed to use the key; your application does not receive the customer’s cloud credentials or raw KMS key material.

Test before production

Use cloud accounts you control to verify:

1. encrypt and decrypt with each provider you offer;
2. failure when key access is disabled or revoked;
3. recovery when access is restored; and
4. removal of a customer connection.

Tell customers what disabling the key does. Your application can keep the ciphertext. The Encrypt/Decrypt API may continue using a root already cached for up to five minutes; after that cache expires, decrypt fails until key access returns.

Keep the customer ID server-side

Resolve X-Alien-External-ID from the authenticated tenant in your backend. Do not accept an arbitrary customer ID from browser code.

Use a different keyId when you want separate cryptographic contexts, such as documents, credentials, or customer-data.

Inspect usage

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

The aggregate includes request, success, error, and latency totals when the project’s metrics source is available.