Skip to content

Posh-ACME examples

These PowerShell examples request and renew certificates with Posh-ACME while sending the same CertIntel requests as scripts/simple-acme/:

  • /api/v1/checkins/start before every client run
  • /api/v1/checkins after every client run, including no-op renewal checks
  • /api/v1/renewals/enrich for each issued certificate, with thumbprints, validity, SANs, and Posh-ACME's PFX path
  • /api/v1/renewals for each successful issuance or failed attempt

Files

  • Request-Certificate.ps1 wraps Posh-ACME's New-PACertificate.
  • Renew-Certificates.ps1 checks one or every order on the current account with Submit-Renewal.
  • CertIntel-Common.ps1 contains the shared API payload helpers and is not run directly.

The scripts support Windows PowerShell 5.1 and PowerShell 7+. Install Posh-ACME first:

Install-Module Posh-ACME -Scope CurrentUser

Create a unique write-scoped CertIntel key for this device (scoped to the target organization, with both renewals and checkins enabled). Authentication is a single header, X-Api-Key: cik_<prefix>.<secret>. Set the configuration in the account that will run Posh-ACME:

$env:CERTINTEL_API_URL = 'https://acme-corp.certintel.example/api/v1/renewals'
$env:CERTINTEL_CHECKINS_URL = 'https://acme-corp.certintel.example/api/v1/checkins'
$env:CERTINTEL_API_KEY = 'cik_XXXXXXXX.YYYYYYYYYYYYYYYYYYYYYYYY'   # full write-scoped token

For a persistent scheduled task, define those as machine/user environment variables or set them in a protected launcher script. Do not put the key secret in task arguments.

Request a certificate

The default Manual plugin prompts for DNS records and is useful for a first test:

./Request-Certificate.ps1 `
    -Domain 'example.com','www.example.com' `
    -Contact 'admin@example.com' `
    -AcceptTOS

Automated renewals require an unattended validation plugin. For example, Posh-ACME's WebRoot plugin:

$pluginArgs = @{ WebRoot = 'C:\inetpub\wwwroot' }
./Request-Certificate.ps1 `
    -Domain 'example.com','www.example.com' `
    -Contact 'admin@example.com' `
    -Plugin WebRoot `
    -PluginArgs $pluginArgs `
    -AcceptTOS

Use Get-PAPlugin <PluginName> -Guide for the exact arguments required by a DNS or HTTP plugin. Secrets placed in PluginArgs are passed to Posh-ACME and are never included in CertIntel payloads.

Renew certificates

Check every order on the current Posh-ACME account:

./Renew-Certificates.ps1

Or check one named order:

./Renew-Certificates.ps1 -MainDomain 'example.com' -Name 'example.com'

Schedule this script instead of calling Submit-Renewal directly. An order that is not due produces only the start/completion check-ins. Posh-ACME returns a certificate object only for an order actually renewed, and only those orders produce enrich/renewal events. The script exits non-zero if any attempted order fails, so Task Scheduler or another scheduler retains a useful result code.

-Force is intended for controlled testing, not routine schedules. It can consume CA rate limits quickly. Manual DNS orders are skipped by default; -NoSkipManualDns may prompt and is therefore unsuitable for unattended jobs.

Official command references: