AWS.ACM reference

AccountConfiguration

Source: packages/aws/src/ACM/AccountConfiguration.ts

Account-level ACM configuration (AWS::CertificateManager::Account).

ACM emits one ACM Certificate Approaching Expiration EventBridge event per day per certificate starting daysBeforeExpiry days before each certificate expires. This account-global singleton manages that threshold via acm:PutAccountConfiguration. Deleting the resource resets the threshold to the AWS default of 45 days.

Like the Certificate resource, the provider pins its API calls to us-east-1.

AccountConfiguration: Configuring Expiry Events

Start Expiry Events 30 Days Before Expiration

const config = yield* AccountConfiguration("AcmAccount", {
  daysBeforeExpiry: "30 days",
});

Consume the Expiry Events

// The events arrive on the default EventBridge bus with source "aws.acm".
yield* AWS.ACM.consumeExpiryEvents({}, (events) =>
  Stream.runForEach(events, (event) =>
    Effect.log(
      `${event.detail.CommonName} expires in ${event.detail.DaysToExpiry} days`,
    ),
  ),
);

Certificate

Source: packages/aws/src/ACM/Certificate.ts

An ACM certificate for CloudFront and other AWS endpoints.

Certificate requests an ACM certificate in us-east-1, which is the region required for CloudFront viewer certificates. With DNS validation, the provider creates or updates the Route 53 validation records (hostedZoneId, or the inferred public zone) and waits for the certificate to be issued. With dnsValidation: "external" the records are published elsewhere — e.g. through a DNS adapter — and AWS.ACM.CertificateValidation waits for issuance.

Certificate: Requesting Certificates

DNS-Validated Certificate

const cert = yield* Certificate("WebsiteCertificate", {
  domainName: "www.example.com",
  hostedZoneId: "Z1234567890",
});

Certificate With SANs

const cert = yield* Certificate("WebsiteCertificate", {
  domainName: "example.com",
  subjectAlternativeNames: ["www.example.com"],
  hostedZoneId: "Z1234567890",
});

Exportable Certificate

// `export: "ENABLED"` lets the ExportCertificate binding retrieve the
// certificate together with its (encrypted) private key at runtime.
const cert = yield* Certificate("ExportableCertificate", {
  domainName: "www.example.com",
  hostedZoneId: "Z1234567890",
  export: "ENABLED",
});

Certificate Validated Through Another DNS Host

// DNS lives in Cloudflare: publish ACM's validation CNAMEs through the
// Cloudflare DNS adapter, then wait for issuance. AWS composites do this
// for you when `domain.dns` is set.
const cert = yield* Certificate("WebsiteCertificate", {
  domainName: "www.example.com",
  dnsValidation: "external",
});
const dns = yield* DNS.resolve(Cloudflare.DNS.Adapter());
yield* dns.records("WebsiteCertificateValidation", {
  records: cert.domainValidationOptions.pipe(
    Output.map(validationRecordsOf),
  ),
  retain: true,
});
const issued = yield* CertificateValidation("WebsiteCertificateIssued", {
  certificateArn: cert.certificateArn,
});

Certificate: Certificate Expiry Events

// ACM emits "ACM Certificate Approaching Expiration" events through
// EventBridge — consume them with the ACM expiry event source, scoped
// to this certificate.
yield* AWS.ACM.consumeExpiryEvents(
  { certificateArns: [cert.certificateArn] },
  (events) =>
    Stream.runForEach(events, (event) =>
      Effect.log(
        `${event.detail.CommonName} expires in ${event.detail.DaysToExpiry} days`,
      ),
    ),
);

Certificate: Looking up an existing certificate

Certificate.lookup references a certificate Alchemy doesn’t manage (created in the console or by another stack), found by certificateArn, or the domainName an issued certificate covers. It is read during plan/deploy and never created, updated or deleted.

const cert = AWS.ACM.Certificate.lookup({
  domainName: "www.example.com",
  region: "us-east-1",
});

CertificateValidation

Source: packages/aws/src/ACM/CertificateValidation.ts

Waits for a DNS-validated ACM certificate to be issued.

Pair it with an AWS.ACM.Certificate requested with dnsValidation: "external" whose validation records are published elsewhere — typically through a DNS adapter (see DNS Adapters). Resources that need an issued certificate (a CloudFront distribution, an HTTPS listener, an API Gateway domain) take this resource’s certificateArn, so they deploy only after issuance. Deleting it deletes nothing.

A CAA_ERROR fails with CertificateCaaError, naming the CAA records to add. Issuance is polled for up to ten minutes.

CertificateValidation: Waiting For Issuance

const cert = yield* AWS.ACM.Certificate("Cert", {
  domainName: "app.example.com",
  dnsValidation: "external",
});
yield* Cloudflare.DNS.RecordList("CertValidation", {
  records: cert.domainValidationOptions.pipe(
    Output.map(AWS.ACM.validationRecordsOf),
  ),
});
const issued = yield* AWS.ACM.CertificateValidation("CertIssued", {
  certificateArn: cert.certificateArn,
});
// issued.certificateArn is safe to attach to a distribution or listener.

DescribeCertificate

Source: packages/aws/src/ACM/DescribeCertificate.ts

Runtime binding for acm:DescribeCertificate.

Bind this operation to a Certificate to get a callable that reads the certificate’s live metadata — status, domain validation state, renewal summary, expiry — from inside a function runtime. Useful for expiry monitors and issuance dashboards. Provide the implementation with Effect.provide(AWS.ACM.DescribeCertificateHttp).

DescribeCertificate: Inspecting Certificates

// init — bind the operation to the certificate
const describeCertificate = yield* AWS.ACM.DescribeCertificate(certificate);

// runtime
const { Certificate: detail } = yield* describeCertificate();
const status = detail?.Status;
const notAfter = detail?.NotAfter;

ExportCertificate

Source: packages/aws/src/ACM/ExportCertificate.ts

Runtime binding for acm:ExportCertificate.

Bind this operation to a Certificate to get a callable that exports the certificate, its chain, and the encrypted private key. Only exportable certificates can be exported: private-CA certificates, or public certificates requested with export: "ENABLED". The returned PrivateKey is sensitive and comes back wrapped in Redacted — unwrap it with Redacted.value only at the point of use. Provide the implementation with Effect.provide(AWS.ACM.ExportCertificateHttp).

ExportCertificate: Exporting Certificates

// init — bind the operation to the certificate
const exportCertificate = yield* AWS.ACM.ExportCertificate(certificate);

// runtime — the passphrase encrypts the exported private key
const result = yield* exportCertificate({
  Passphrase: Redacted.make(new TextEncoder().encode(passphrase)),
});
const pem = result.Certificate;
const privateKeyPem =
  typeof result.PrivateKey === "string"
    ? result.PrivateKey
    : result.PrivateKey && Redacted.value(result.PrivateKey);

GetCertificate

Source: packages/aws/src/ACM/GetCertificate.ts

Runtime binding for acm:GetCertificate.

Bind this operation to a Certificate to get a callable that retrieves the issued certificate body and its certificate chain (both PEM-encoded). The certificate must be issued — a certificate that is still pending validation fails with the typed RequestInProgressException. Provide the implementation with Effect.provide(AWS.ACM.GetCertificateHttp).

GetCertificate: Reading Certificates

Fetch the PEM Certificate Chain

// init — bind the operation to the certificate
const getCertificate = yield* AWS.ACM.GetCertificate(certificate);

// runtime
const result = yield* getCertificate();
const pem = result.Certificate;
const chain = result.CertificateChain;

Handle a Certificate That Is Not Issued Yet

const pem = yield* getCertificate().pipe(
  Effect.map((result) => result.Certificate),
  Effect.catchTag("RequestInProgressException", () =>
    Effect.succeed(undefined),
  ),
);

ImportCertificate

Source: packages/aws/src/ACM/ImportCertificate.ts

Runtime binding for acm:ImportCertificate.

An account-level operation (no certificate argument) that imports an externally issued certificate into ACM in us-east-1 — the classic rotation flow where a function obtains a renewed certificate from an outside CA and re-imports it over the existing ACM entry by passing its CertificateArn. Provide the implementation with Effect.provide(AWS.ACM.ImportCertificateHttp).

ImportCertificate: Importing Certificates

// init — account-level binding takes no resource
const importCertificate = yield* AWS.ACM.ImportCertificate();

// runtime — re-import a renewed certificate over the existing ARN
const encoder = new TextEncoder();
const result = yield* importCertificate({
  CertificateArn: existingArn,
  Certificate: encoder.encode(certificatePem),
  PrivateKey: Redacted.make(encoder.encode(privateKeyPem)),
  CertificateChain: encoder.encode(chainPem),
});

ListCertificates

Source: packages/aws/src/ACM/ListCertificates.ts

Runtime binding for acm:ListCertificates.

An account-level operation (no certificate argument) that enumerates the ACM certificates in us-east-1 — the region where alchemy-managed certificates live. Useful for expiry monitors that sweep every certificate in the account. Note that the default filter only returns RSA_2048 certificates; pass Includes.keyTypes to widen it. Provide the implementation with Effect.provide(AWS.ACM.ListCertificatesHttp).

ListCertificates: Inspecting Certificates

// init — account-level binding takes no resource
const listCertificates = yield* AWS.ACM.ListCertificates();

// runtime
const result = yield* listCertificates({
  CertificateStatuses: ["ISSUED"],
});
const expiring = (result.CertificateSummaryList ?? []).filter(
  (summary) =>
    summary.NotAfter !== undefined &&
    summary.NotAfter.getTime() - Date.now() < 30 * 24 * 60 * 60 * 1000,
);

RenewCertificate

Source: packages/aws/src/ACM/RenewCertificate.ts

Runtime binding for acm:RenewCertificate.

Bind this operation to a Certificate to get a callable that forces managed renewal of an eligible certificate — typically an exported certificate whose renewal is not fully automatic. Useful in rotation functions that renew and then re-export a certificate. Provide the implementation with Effect.provide(AWS.ACM.RenewCertificateHttp).

RenewCertificate: Renewing Certificates

// init — bind the operation to the certificate
const renewCertificate = yield* AWS.ACM.RenewCertificate(certificate);

// runtime
yield* renewCertificate();

ResendValidationEmail

Source: packages/aws/src/ACM/ResendValidationEmail.ts

Runtime binding for acm:ResendValidationEmail.

Bind this operation to a Certificate requested with validationMethod: "EMAIL" to get a callable that re-sends the domain ownership validation email — e.g. behind a “resend email” button in an onboarding flow. Calling it on a DNS-validated certificate fails with the typed InvalidStateException. Provide the implementation with Effect.provide(AWS.ACM.ResendValidationEmailHttp).

ResendValidationEmail: Validating Certificates

// init — bind the operation to the certificate
const resendValidationEmail =
  yield* AWS.ACM.ResendValidationEmail(certificate);

// runtime
yield* resendValidationEmail({
  Domain: "www.example.com",
  ValidationDomain: "example.com",
});

RevokeCertificate

Source: packages/aws/src/ACM/RevokeCertificate.ts

Runtime binding for acm:RevokeCertificate.

Bind this operation to a Certificate to get a callable that revokes a previously exported public certificate — e.g. from a security-automation function reacting to a leaked private key. Revocation is permanent. Provide the implementation with Effect.provide(AWS.ACM.RevokeCertificateHttp).

RevokeCertificate: Revoking Certificates

// init — bind the operation to the certificate
const revokeCertificate = yield* AWS.ACM.RevokeCertificate(certificate);

// runtime
yield* revokeCertificate({ RevocationReason: "KEY_COMPROMISE" });

SearchCertificates

Source: packages/aws/src/ACM/SearchCertificates.ts

Runtime binding for acm:SearchCertificates.

An account-level operation (no certificate argument) that searches the ACM certificates in us-east-1 with richer filtering than ListCertificates — X.509 attributes, status, type, and renewal eligibility can be combined in a filter statement. Provide the implementation with Effect.provide(AWS.ACM.SearchCertificatesHttp).

SearchCertificates: Inspecting Certificates

// init — account-level binding takes no resource
const searchCertificates = yield* AWS.ACM.SearchCertificates();

// runtime
const result = yield* searchCertificates({
  FilterStatement: { Filter: { CertificateArn: certificateArn } },
});
const arns = (result.Results ?? []).map((r) => r.CertificateArn);