ACME Overview #

ACME allows clients to trigger certificate management actions using a set of JSON messages. Issuance using ACME resembles a traditional CA’s issuance process, in which a client:

Creates an account.
Initiates an order for a certificate to be issued.
Proves control of all identifiers (domain names, IP addresses, etc.) requested to be included in the certificate.
Finalizes the order by submitting a CSR (Certificate Signing Request).
Awaits issuance and downloads the issued certificate along with the corresponding chain(s).

This pages introduces the most important concepts and provides a high-level explanation of the ACME protocol. Refer to RFC 8555 for additional information.

Directory URL #

Since ACME is a standardized protocol, any ACME client can request certificates from any ACME CA (Certificate Authority). The client only needs to configure one thing: the ACME Directory URL.

The ACME Directory URL returns everything the client needs to know to interact with the ACME CA. For example, Google Trust Services’ ACME Directory URL is https://dv.acme-v02.api.pki.goog/directory. Here is the response from an HTTP GET request to that URL.

{
  "newNonce": "https://dv.acme-v02.api.pki.goog/new-nonce",
  "newAccount": "https://dv.acme-v02.api.pki.goog/new-account",
  "newOrder": "https://dv.acme-v02.api.pki.goog/new-order",
  "newAuthz": "https://dv.acme-v02.api.pki.goog/new-authz",
  "revokeCert": "https://dv.acme-v02.api.pki.goog/revoke-cert",
  "keyChange": "https://dv.acme-v02.api.pki.goog/key-change",
  "renewalInfo": "https://dv.acme-v02.api.pki.goog/renewal-info",
  "meta": {
    "termsOfService": "https://pki.goog/GTS-SA.pdf",
    "website": "https://pki.goog",
    "caaIdentities": ["pki.goog"],
    "externalAccountRequired": true
  }
}

The returned JSON object lists URLs for various certificate management actions, such as creating a new account (newAccount) or initiating a new order (newOrder). The JSON object also holds metadata that links to various resources, specifies the CAA identities that the CA recognizes as referring to itself, and indicates whether EAB (External Account Binding) is required for creating an ACME account.

Account #

Before creating a new ACME account, the client must generate an asymmetric key pair. The client uses the generated ACME account private key to authenticate themselves by signing all messages sent to the CA. There is no username, the key pair suffices. See Request Protection below.

New ACME accounts are created by sending an HTTP POST request to the newAccount URL. The previously generated ACME account public key must be set in the jwk (JSON Web Key) field of the request’s JWS (JSON Web Signature). The CA will use it to authenticate future requests from that account.

When creating a new account, the client must set termsOfServiceAgreed to true in the request. This attests that they read and agree to the terms of service linked from meta.termsOfService in the JSON object returned by the ACME Directory URL.

Clients can also provide a contact URL, usually a mailto: email address, that the CA can use to notify them about upcoming certificates expiries, upcoming certificate revocations caused by external factors, or Certificate Problem Reports received by the CA. Note that Let’s Encrypt stopped sending expiry notification emails in 2025 and ARI (ACME Renewal Information) should be used instead to automatically know when certificates should be renewed and proactively renew them if they are going to be affected by upcoming revocations caused by external factors.

Finally, if meta.externalAccountRequired is true in the JSON object returned by the ACME Directory URL, the newAccount request must include the externalAccountBinding field. This is used to associate the ACME account with an existing account in a non-ACME system, such as a CA customer database. The value of the externalAccountBinding field is described in RFC 8555. The important thing is that its value depends on a MAC (Message Authentication Code) key and a key identifier which must both be previously provided by the CA using a mechanism outside of ACME. See the page dedicated to External Account Binding for more information.

Click here to view an example newAccount request.

POST /acme/new-account HTTP/1.1
Host: example.com
Content-Type: application/jose+json

The request body below is not valid JSON since it includes base64url() function calls and some values are truncated. It intends to show how the values of the JSON object are computed.

{
  "protected": base64url({
    "alg": "ES256",
    "jwk": {...},
    "nonce": "6S8IqOGY7eL2lsGoTZYifg",
    "url": "https://example.com/acme/new-account"
  }),
  "payload": base64url({
    "termsOfServiceAgreed": true,
    "contact": [
      "mailto:[email protected]",
      "mailto:[email protected]"
    ]
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

Request Protection #

Most ACME requests:

Must have a JSON body signed using the ACME account private key.
Must have a “kid” (Key ID) field which references the ACME account URL to which the key is bound.
Must use the HTTP POST method since HTTP GET requests can’t have a body.
Must include an unpredictable nonce to protect against replay attacks.
Must include a “url” field (part of the signed JSON body) which specifies the URL to which the request is directed to protect against compromised CDNs (Content Delivery Networks).
Must have the Content-Type HTTP header field set to “application/jose+json”.

These requirements ensure that all requests that must be restricted to only a specific ACME account are authenticated appropriately. The CA maintains a list of nonces that it has issued, and it requires any signed request from clients to carry such a nonce. Clients can get fresh nonces from the Replay-Nonce HTTP header included in all responses from the CA or by sending an HTTP HEAD request to the newNonce URL.

To fetch resources (which would otherwise be done using the HTTP GET method), clients must send HTTP POST requests with a JWS (JSON Web Signature) body having the payload field set to the empty string (""). Such requests are referred to as “POST-as-GET” requests.

There are a few exceptions to these rules. For example, the Directory URL can be fetched using a simple HTTP GET request, or revokeCert requests can be signed using the certificate private key instead of the account private key.

Order Initiation #

New certificate orders are created by sending an HTTP POST request to the newOrder URL. The JSON body of the request must include the identifiers (domain names and IP addresses) that the client wishes to include in the certificate and, optionally, the notBefore/notAfter timestamps that determine the certificate’s validity. If they aren’t set, the CA sets sane default values instead. See the page dedicated to certificate lifetimes for more information.

If the CA is willing to issue the requested certificate, it responds with a 201 (Created) HTTP status. The JSON body of the response contains the URL of all authorizations the client must complete before the certificate can be issued. The client must send POST-as-GET requests to the indicated URLs to fetch detailed information about the authorization resources tied to the order.

See the Domain Control Validation section below to understand how authorizations can be completed.

Click here to view an example newOrder response.

HTTP/1.1 201 Created
Replay-Nonce: MYAuvOpaoIiywTezizk5vw
Link: <https://example.com/acme/directory>;rel="index"
Location: https://example.com/acme/order/TOlocE8rfgo

{
  "status": "pending",
  "expires": "2025-05-05T14:09:07.99Z",
  "notBefore": "2025-05-01T00:00:00Z",
  "notAfter": "2025-05-07T23:59:59Z",
  "identifiers": [
    { "type": "dns", "value": "www.example.org" },
    { "type": "dns", "value": "example.org" }
  ],
  "authorizations": [
    "https://example.com/acme/authz/PAniVnsZcis",
    "https://example.com/acme/authz/r4HqLzrSrpI"
  ],
  "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize"
}

Click here to view an example authorization resource.

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://example.com/acme/directory>;rel="index"

{
  "status": "pending",
  "expires": "2025-05-02T14:09:30Z",
  "identifier": {
    "type": "dns",
    "value": "www.example.org"
  },
  "challenges": [
    {
      "type": "http-01",
      "url": "https://example.com/acme/chall/prV_B7yEyA4",
      "token": "DGyRejmCefe7v4NfDGDKfA"
    },
    {
      "type": "dns-01",
      "url": "https://example.com/acme/chall/Rg5dV14Gh1Q",
      "token": "DGyRejmCefe7v4NfDGDKfA"
    }
  ]
}

There is another (less common) flow to initiate certificate issuances. It is called the “pre-authorization” flow. It consists of first sending an HTTP POST request to the newAuthz URL (new authorization) for all identifiers the client wishes to include in the certificate, then completing all authorizations (see the Domain Control Validation section below), and finally initiating a newOrder, without having to reactively complete the corresponding authorizations since they have all been pre-authorized.

DCV (Domain Control Validation) #

Domain Control Validation, despite its name, applies to both domain names and IP addresses.

An authorization with status “valid” signifies that the tied ACME account is authorized to manage certificates for a given identifier (domain name or IP address). To complete an authorization, the client must complete the DCV (Domain Control Validation) process to prove that they control the identifier in question.

Each authorization has multiple associated challenges, each with a different type. To complete an authorization, the client must solve one of them (the client gets to choose the one they prefer). The most common challenge types are dns-01 and http-01. They require the client to publish a value derived from a token provided by the CA to an agreed upon URL via DNS or HTTP, respectively. It is assumed that the value at the agreed upon URL can only be updated by someone who legitimately controls the identifier.

The client must send an HTTP POST request with an empty JSON body ("{}") to the challenge URL (not the authorization URL) once they are ready for CA to validate a challenge. Upon receiving this request, the CA retrieves content from the agreed upon URL (via DNS or HTTP) and verifies that the fetched data matches the expected value.

To mitigate hijacking attacks, CAs perform the challenge validation from multiple vantage points worldwide. Refer to the page dedicated to MPIC (Multi-Perspective Issuance Corroboration) for more information.

Usually, the validation process takes some time, so the client needs to regularly poll the authorization URL to know when it is completed. Once validated, an authorization can be reused for future certificate issuances (for a limited period of time). In other words, the client doesn’t always have to prove they control an identifier when requesting new certificates for the same domain name.

Order Finalization and Issuance #

Once all authorizations from an order are “valid”, the order transitions to the “ready” state. Newly created orders may immediately be in a “ready” state if all their identifiers were previously authorized.

Orders are finalized by sending an HTTP POST request to the finalize URL found in the JSON object returned by newOrder. This request must only be sent once all corresponding authorizations have been completed.

The request JSON body must include a CSR (Certificate Signing Request) for the certificate being requested. The CSR must indicate the exact same set of identifiers as the initial newOrder request. Generally, the CA only extracts the public key from the CSR and ignores all other attributes and extensions.

Before issuing the certificate, the CA verifies CAA records to ensure that it is authorized to issue a certificate for the requested identifiers.

Once all validations pass, the CA issues the certificate including all requested (and validated) identifiers. To issue the certificate, the CA builds and populates a data structure called a tbsCertificate (to be signed certificate) and signs it using an intermediate CA private key. The tbsCertificate contains the requested identifiers, the public key from the CSR, notBefore/notAfter validity timestamps, SCTs (Signed Certificate Timestamps), and other attributes required to validate the authenticity of the certificate. See the page dedicated to the anatomy of certificates for more information.

The CA then respond with a 200 (OK) HTTP status. The JSON body of the response contains an updated order object having its status set to “valid” and a new “certificate” field that holds the URL for downloading the issued certificate.

To download the issued certificate, the client simply sends an HTTP POST-as-GET request to the certificate URL with the Accept HTTP header set to “application/pem-certificate-chain”. The response from the CA is a series of PEM-encoded certificates, starting with the newly issued certificate, followed by one or more CA certificates necessary to build the chain, without including the self-signed root CA certificate (a.k.a. “trust anchor”).

Click here to view an example certificate response.

HTTP/1.1 200 OK
Content-Type: application/pem-certificate-chain
Link: <https://example.com/acme/directory>;rel="index"

The TLS protocol requires servers to serve certificates which form a chain of trust leading from the TLS web server certificate to a trust anchor. This is why the site for which the certificate just got issued must serve this whole certificate chain to its visitors when establishing HTTPS connections (and not just the newly issued TLS web server certificate).

The response from the CA may also include a Link HTTP header with rel="alternate" pointing to alternative certificate chains (including cross-signed CA certificates) starting with the same TLS web server certificate and ending with different trust anchors. Clients can fetch these alternate chains and use their own heuristics (e.g. the lightest, the most compatible, etc.) to decide which one to serve to visitors of their site.

A certificate resource represents a single, immutable certificate. To renew a certificate, the client must initiate a new order.

Remember that certificates are based on asymmetric cryptography. Certificates only include the public key. The private key must not be shared with anyone, not even the CA who issues the certificate.

Revocation #

Certificates are normally valid between their notBefore and notAfter timestamps. There may be (security, business, compliance, etc.) reasons to invalidate a certificate before its notAfter timestamp. This is what revocation is for.

Certificates can be revoked by sending an HTTP POST request to the revokeCert URL. The JSON body of the request must include the certificate to revoke and can optionally include the desired revocation reasonCode.

Revocation requests are different from other ACME requests in that they can be signed with either an account key pair or the key pair in the certificate (in which case the client doesn’t need to have an ACME account registered with the CA).

There are 3 ways to be authorized to revoke certificates via ACME:

By signing the revocation request using the private key of the ACME account used to issue the certificate (in which case the client is assumed to be the one who requested the certificate in the first place).
By signing the revocation request using the certificate private key (in which case the client is either the one who requested the certificate, or the certificate private key is compromised, and it must be revoked anyway).
By signing the revocation request using the private key of an ACME account that holds “valid” authorizations for all the identifiers in the certificate (in which case the client is the legitimate owner of all identifiers included in the certificate).