Skip to content

REST API

Jump to bottom
Tatsuro Shibamura edited this page Mar 14, 2026 · 14 revisions

REST API

Acmebot exposes an HTTP API for certificate issuance, renewal, revocation, and operation tracking. Certificate operations are asynchronous: when a request is accepted, the API returns 202 Accepted and a status URL in the Location header.

Before you call the API

  • Send JSON request bodies.
  • Authenticate with either a Functions host key or a Microsoft Entra ID bearer token.
  • Poll the operation URL from the Location header until the request completes.

For authentication examples, see API Authentication.

Common headers

Header When required Notes
Content-Type: application/json Request bodies Required for JSON payloads
X-Functions-Key: <functions host key> When using host key authentication Omit when using bearer tokens
Authorization: Bearer <access token> When using Microsoft Entra ID authentication Omit when using host keys

Issue a certificate

Request

POST /api/certificate

Payload

The DnsNames array must contain every DNS name that should be included in the certificate.

{
  "DnsNames": ["contoso.com", "www.contoso.com"]
}

Responses

  • 202 Accepted: the issuance request was queued successfully.
202 Accepted
Location: /api/state/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • 400 Bad Request: the request payload failed validation.
{
  "errors": {
    "DnsNames": [
      "The DnsNames is required."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-e2468d29d2988e4490e92e2768b622b0-92d30024b7066e4d-00"
}
  • 401 Unauthorized: the request did not include valid authentication.

Renew a certificate

Request

POST /api/certificate/{certificate-name}/renew

{certificate-name} is the Key Vault certificate name managed by Acmebot.

Responses

  • 202 Accepted: the renewal request was queued successfully.
202 Accepted
Location: /api/state/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • 401 Unauthorized: the request did not include valid authentication.

Revoke a certificate

Request

POST /api/certificate/{certificate-name}/revoke

Responses

  • 202 Accepted: the revocation request was queued successfully.
202 Accepted
Location: /api/state/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • 401 Unauthorized: the request did not include valid authentication.

Track an asynchronous operation

Use the URL from the Location header exactly as returned by the API.

Request

GET /api/state/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Responses

  • 200 OK: the operation finished successfully.
  • 202 Accepted: the operation is still running. Continue polling the Location URL.
  • 500 Internal Server Error: the operation failed. Review Function App logs or Application Insights for details.

If an operation fails repeatedly, use Troubleshooting to isolate whether the error is caused by DNS validation, Key Vault permissions, authentication, or the consuming Azure service.

Clone this wiki locally