HTTP API

The dashboard uses these same-origin HTTP endpoints. They define the integration surface and operation lifecycle.

All endpoints expect authenticated requests. Issue, renew, and revoke operations may also require app roles when Acmebot__RequireAppRoles=true.

Authentication

The v5 API is intended to be protected by App Service Authentication. For interactive use, users sign in through the dashboard. For automation, call the API with an authenticated principal that App Service Authentication can validate, typically a Microsoft Entra ID bearer token.

Authorization: Bearer <access-token>
Accept: application/json

The HTTP triggers use anonymous trigger authorization internally, but the application code rejects requests without an authenticated user. A Functions host key by itself does not satisfy the dashboard or API authentication checks.

When app role enforcement is enabled, issue and renew operations require Acmebot.IssueCertificate, and revoke operations require Acmebot.RevokeCertificate.

Endpoints

Method	Path	Purpose
GET	/api/certificates	List certificates from Key Vault.
POST	/api/certificates	Start certificate issuance.
POST	/api/certificates/{certificateName}/renew	Start manual renewal.
POST	/api/certificates/{certificateName}/revoke	Revoke a certificate through the ACME certificate authority.
GET	/api/dns-zones	List DNS zones from configured providers.
GET	/api/renewals	List automatic renewal status for certificates.
GET	/api/operations/{instanceId}	Poll an issuance or renewal operation.

Operation Lifecycle

POST /api/certificates and POST /api/certificates/{certificateName}/renew return 202 Accepted with a Location header. Poll that URL until it returns:

Status	Meaning
202	Operation is pending or running.
200	Operation completed.
Problem response	Operation failed.

Issue Certificate

POST /api/certificates
Content-Type: application/json
Accept: application/json

{
  "certificateName": "wildcard-example-com",
  "dnsNames": ["*.example.com"],
  "dnsProviderName": "Azure DNS",
  "keyType": "RSA",
  "keySize": 2048,
  "reuseKey": false,
  "dnsAlias": "acme-validation.example.net",
  "profile": "tlsserver",
  "tags": {
    "owner": "platform"
  }
}

Request Fields

Property	Required	Description
certificateName	Yes	Key Vault certificate name. API clients must provide this value. It must be 1 to 127 characters and contain only letters, numbers, and hyphens.
dnsNames	Yes	ASCII/punycode DNS names to include in the certificate. Omit trailing dots. Wildcards are allowed only as the leftmost label.
dnsProviderName	Yes	Provider display name, such as Azure DNS or Cloudflare. When dnsAlias is set, this provider must manage the DNS alias zone.
keyType	Yes	RSA or EC.
keySize	For RSA	2048, 3072, or 4096.
keyCurveName	For EC	P-256, P-384, P-521, or P-256K.
reuseKey	No	Whether Key Vault should reuse the certificate key.
dnsAlias	No	Alternate ASCII/punycode domain used for DNS-01 validation. Acmebot writes TXT records at _acme-challenge.<dnsAlias>, so omit the _acme-challenge prefix and trailing dot from this value.
profile	No	ACME profile to request for this certificate. When omitted, Acmebot uses Acmebot__PreferredProfile if configured.
tags	No	Custom Key Vault certificate tags. Acmebot is reserved.

For delegated DNS-01 validation, set dnsNames to the certificate names and set dnsAlias to a unique record in a zone Acmebot can update. For each DNS name, create a CNAME from _acme-challenge.<dnsName> to _acme-challenge.<dnsAlias> in the authoritative DNS provider for the certificate domain.

List Certificates

GET /api/certificates
Accept: application/json

Returns an array of certificate objects.

[
  {
    "id": "https://my-vault.vault.azure.net/certificates/wildcard-example-com/...",
    "name": "wildcard-example-com",
    "dnsNames": ["*.example.com"],
    "dnsProviderName": "Azure DNS",
    "createdOn": "2026-05-01T00:00:00+00:00",
    "expiresOn": "2026-07-30T00:00:00+00:00",
    "x509Thumbprint": "ABCDEF...",
    "keyType": "RSA",
    "keySize": 2048,
    "reuseKey": false,
    "enabled": true,
    "isIssuedByAcmebot": true,
    "isSameEndpoint": true,
    "acmeEndpoint": "acme-v02.api.letsencrypt.org",
    "dnsAlias": "",
    "tags": {
      "owner": "platform"
    }
  }
]

List DNS Zones

GET /api/dns-zones
Accept: application/json

[
  {
    "dnsProviderName": "Azure DNS",
    "dnsZones": [
      { "name": "example.com" }
    ]
  }
]

List Renewal Status

GET /api/renewals
Accept: application/json

Returns automatic renewal status for certificates visible to Acmebot.

[
  {
    "certificateName": "wildcard-example-com",
    "status": "Scheduled",
    "statusKind": "scheduled",
    "message": "Renewal is scheduled within the certificate authority's suggested renewal window.",
    "nextCheck": "2026-06-20T00:00:00+00:00",
    "lastCheckedAt": "2026-06-19T00:00:00+00:00"
  }
]

Manual Renewal

POST /api/certificates/wildcard-example-com/renew
Accept: application/json

Returns 202 Accepted with a Location header for operation polling. Renewal restores the per-certificate ACME profile saved in Acmebot metadata; certificates without one use the deployment-level Acmebot__PreferredProfile setting when configured.

Revocation

POST /api/certificates/wildcard-example-com/revoke
Accept: application/json

Revocation waits for the ACME revoke operation to complete, disables the current Key Vault certificate version, and returns 200 OK on success.

Errors

Validation errors return a problem response that may include field-specific errors. Orchestration failures return problem details from the failed Durable Functions instance.

Common statuses:

Status	Meaning
401	Request is not authenticated.
403	User does not have the required app role.
400	Request validation failed or operation instance was not found.
500	Operation failed unexpectedly.