Secrets and environment variables

Self-managed hosting distinguishes between three kinds of values you can make available to your server-side compute:

• Plain environment variables — non-sensitive literals baked into the CloudFormation template.
• Secrets — sensitive values (API keys, credentials) stored in AWS Secrets Manager.
• Configuration — non-sensitive but rotatable values stored in AWS Systems Manager (SSM) Parameter Store.

Secrets and configuration are referenced by key in your infrastructure. Only the store locator is injected into your compute — the value itself never enters the CloudFormation template and can be changed without a redeploy.

Plain environment variables

Use the environment option for non-sensitive literals such as feature flags, region names, or public URLs. These appear in plaintext in the CloudFormation template, so never put a secret here.

import { defineHosting } from '@aws-amplify/hosting';

export const hosting = defineHosting({
  environment: {
    APP_REGION: 'us-east-1',
    ENABLE_BETA_FEATURES: 'false'
  }
});

Read them at runtime with the standard process.env:

const region = process.env.APP_REGION;

Secrets

For a sensitive value, reference it with secret('KEY'). This tells the hosting construct to inject a locator for a value stored in AWS Secrets Manager — the value never enters the template.

import { defineHosting, secret } from '@aws-amplify/hosting';

export const hosting = defineHosting({
  environment: {
    STRIPE_SECRET_KEY: secret('STRIPE_SECRET_KEY')
  }
});

Set the value out of band with the ampx secret command before (or after) you deploy:

npx ampx secret set STRIPE_SECRET_KEY sk_live_xxx

Then read it at runtime from the CDK-free runtime entry:

import { getSecret } from '@aws-amplify/hosting/runtime';

const stripeKey = await getSecret('STRIPE_SECRET_KEY');

Configuration

Configuration values behave like secrets but are stored in SSM Parameter Store. Use them for values that are not sensitive but should be changeable without a redeploy (for example, a per-environment domain or a feature-flag payload). Reference them with config('KEY') and read them with getConfig('KEY').

import { defineHosting, config } from '@aws-amplify/hosting';

export const hosting = defineHosting({
  environment: {
    FEATURE_FLAGS: config('FEATURE_FLAGS')
  }
});

npx ampx config set FEATURE_FLAGS '{"newCheckout":true}'

import { getConfig } from '@aws-amplify/hosting/runtime';

const flags = JSON.parse(await getConfig('FEATURE_FLAGS'));

Both command families support set, get, list, and remove — for example npx ampx secret list or npx ampx config remove FEATURE_FLAGS.

Referencing existing resources

If a secret or parameter already exists (managed by another team, stack, or process), reference it directly instead of having Amplify manage it. Use byoSecret() with a Secrets Manager name or ARN, and byoConfig() with an SSM parameter name. No CLI set step is required — you manage the value externally.

import { defineHosting, byoSecret, byoConfig } from '@aws-amplify/hosting';

export const hosting = defineHosting({
  environment: {
    DB_PASSWORD: byoSecret('arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/db-AbCdEf'),
    LAUNCH_DARKLY_ENV: byoConfig('/my-org/launchdarkly/prod')
  }
});

Read them the same way — getSecret('DB_PASSWORD') and getConfig('LAUNCH_DARKLY_ENV').

Where values are stored

By default, Amplify namespaces the stores per project so multiple apps in one account do not collide:

• Secrets: /amplify/hosting/<project>/secrets/<KEY>
• Config: /amplify/hosting/<project>/config/<KEY>

Override the prefix — or add a per-stage segment — with the secretStore and configStore options. A stage resolves to <prefix>/<stage>/<KEY> and falls back to the shared <prefix>/<KEY>, which is useful when several pipeline stages share one store.

import { defineHosting, secret } from '@aws-amplify/hosting';

export const hosting = defineHosting({
  environment: {
    STRIPE_SECRET_KEY: secret('STRIPE_SECRET_KEY')
  },
  secretStore: {
    prefix: '/my-org/hosting/secrets',
    stage: 'prod'
  }
});

Next steps

• Configure hosting for domains, WAF, and compute
• Set up a CI/CD pipeline with per-stage configuration