Posh-ACME examples¶

The CertIntel Agent is the preferred method for certificate workflows, renewals and reporting. Its built-in scheduling and reporting make setup and maintenance easier; see the Windows Agent or Linux Agent setup guide. These API reporting examples are an optional alternative when you want to keep Posh-ACME as the renewal owner.

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 with Posh-ACME 4.7+ (4.x). Install Posh-ACME first:

Install-Module Posh-ACME -MinimumVersion 4.7.0 -MaximumVersion 4.999.999 -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://api.certin.tel/api/v1/renewals'
$env:CERTINTEL_CHECKINS_URL = 'https://api.certin.tel/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¶

CertIntel DNS-01 plugin¶

First install CertIntel.ps1 and create the delegation/CNAME. The DNS plugin has been tested successfully; these additional reporting wrappers remain examples to verify in your environment. Pass the DNS secret as a SecureString; keep the separate reporting key in CERTINTEL_API_KEY.

$pluginArgs = @{
    CertIntelDomain       = 'example.com'
    CertIntelDelegationId = '11111111-1111-1111-1111-111111111111'
    CertIntelCnameTarget  = 'YOUR-LABEL.dns01.certin.tel'
    CertIntelApiKey       = Read-Host 'Delegation update secret' -AsSecureString
}
./Request-Certificate.ps1 `
    -Domain 'example.com','*.example.com' `
    -Contact '[email protected]' -AcceptTOS `
    -Plugin CertIntel -PluginArgs $pluginArgs `
    -PluginDirectory 'C:\CertIntel\plugins' -DnsSleep 60 `
    -DirectoryUrl LE_STAGE

Use the folder you downloaded CertIntel.ps1 into (the plugin guide uses %LOCALAPPDATA%\CertIntel\Posh-ACME\Plugins, or %ProgramData%\CertIntel\Posh-ACME\Plugins for all users). -PluginDirectory sets POSHACME_PLUGINS before importing the module; if omitted, the existing environment setting is used. -DnsSleep is optional and leaves Posh-ACME's default intact when omitted. Use -DirectoryUrl LE_PROD for production after staging succeeds. Staging issuance through this wrapper is reported to CertIntel; use a test organization/reporting key to keep it out of production history.

Renew the saved production order with the same account and plugin directory:

./Renew-Certificates.ps1 -MainDomain 'example.com' `
    -PluginDirectory 'C:\CertIntel\plugins' -DirectoryUrl LE_PROD

Saved DNS credentials are reused without a prompt. Preserve any POSHACME_HOME or vault settings in the scheduled process. These wrappers operate on the current Posh-ACME account; select the intended account before calling them if you use more than one. Renewing certificate files does not automatically update an IIS binding or reload an application; configure deployment separately.

Other validation plugins¶

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 '[email protected]' `
    -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 '[email protected]' `
    -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:

• New-PACertificate
• Submit-Renewal
• Get-PACertificate