ACME - Automatic Certificate Management Environment (RFC 8555)

openapi: 3.1.0
info:
  title: ACME (RFC 8555) Protocol API
  description: >-
    The Automatic Certificate Management Environment (ACME) protocol, defined
    in IETF RFC 8555, automates the interactions between Certificate
    Authorities and clients for issuing, renewing, and revoking X.509
    certificates. ACME requests are JSON Web Signature (JWS) payloads carried
    over HTTPS. Server URLs are advertised by each ACME directory; this spec
    uses generic /acme/* paths.
  version: 1.0.0
  contact:
    name: IETF Datatracker
    url: https://datatracker.ietf.org/doc/html/rfc8555
  license:
    name: IETF Trust
    url: https://trustee.ietf.org/license-info
x-generated-from: https://datatracker.ietf.org/doc/html/rfc8555
x-generated-by: claude-crawl-2026-05-08
servers:
  - url: https://acme-v02.api.letsencrypt.org
    description: Let's Encrypt production ACME directory (reference implementation)
  - url: https://acme-staging-v02.api.letsencrypt.org
    description: Let's Encrypt staging ACME directory
tags:
  - name: Directory
    description: Server discovery and nonce retrieval.
  - name: Account
    description: Account creation and key management.
  - name: Order
    description: Certificate order workflow.
  - name: Authorization
    description: Domain authorization and challenges.
  - name: Certificate
    description: Issued certificate retrieval and revocation.
paths:
  /directory:
    get:
      operationId: getDirectory
      summary: Retrieve ACME directory
      description: Returns URLs for the supported resources of this ACME server.
      tags:
        - Directory
      responses:
        '200':
          description: Directory of ACME endpoints
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /acme/new-nonce:
    head:
      operationId: newNonce
      summary: Retrieve a new nonce
      description: Retrieve a fresh anti-replay nonce in the Replay-Nonce header.
      tags:
        - Directory
      responses:
        '200':
          description: Nonce returned in Replay-Nonce header
          headers:
            Replay-Nonce:
              schema:
                type: string
  /acme/new-account:
    post:
      operationId: newAccount
      summary: Create or look up an account
      description: Create a new ACME account or retrieve an existing one. Body is a JWS object.
      tags:
        - Account
      requestBody:
        required: true
        content:
          application/jose+json:
            schema:
              $ref: '#/components/schemas/JwsRequest'
      responses:
        '201':
          description: Account created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '200':
          description: Existing account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /acme/new-order:
    post:
      operationId: newOrder
      summary: Submit a certificate order
      description: Submit a certificate issuance order with identifiers (e.g. DNS names).
      tags:
        - Order
      requestBody:
        required: true
        content:
          application/jose+json:
            schema:
              $ref: '#/components/schemas/JwsRequest'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /acme/order/{id}:
    post:
      operationId: getOrder
      summary: Retrieve an order
      description: Fetch order status and details (POST-as-GET signed request).
      tags:
        - Order
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/jose+json:
            schema:
              $ref: '#/components/schemas/JwsRequest'
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /acme/order/{id}/finalize:
    post:
      operationId: finalizeOrder
      summary: Finalize an order
      description: Finalize a ready order by submitting a CSR.
      tags:
        - Order
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/jose+json:
            schema:
              $ref: '#/components/schemas/JwsRequest'
      responses:
        '200':
          description: Finalized order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /acme/authz/{id}:
    post:
      operationId: getAuthorization
      summary: Retrieve an authorization
      description: Retrieve an authorization, including its challenges (POST-as-GET).
      tags:
        - Authorization
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/jose+json:
            schema:
              $ref: '#/components/schemas/JwsRequest'
      responses:
        '200':
          description: Authorization details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /acme/chall/{id}:
    post:
      operationId: respondToChallenge
      summary: Respond to a challenge
      description: Submit a challenge response indicating the client is ready for validation.
      tags:
        - Authorization
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/jose+json:
            schema:
              $ref: '#/components/schemas/JwsRequest'
      responses:
        '200':
          description: Challenge updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /acme/cert/{id}:
    post:
      operationId: downloadCertificate
      summary: Download an issued certificate
      description: Download an issued certificate chain (PEM, POST-as-GET).
      tags:
        - Certificate
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/jose+json:
            schema:
              $ref: '#/components/schemas/JwsRequest'
      responses:
        '200':
          description: Certificate chain
          content:
            application/pem-certificate-chain:
              schema:
                type: string
  /acme/revoke-cert:
    post:
      operationId: revokeCertificate
      summary: Revoke a certificate
      description: Revoke a previously issued certificate.
      tags:
        - Certificate
      requestBody:
        required: true
        content:
          application/jose+json:
            schema:
              $ref: '#/components/schemas/JwsRequest'
      responses:
        '200':
          description: Certificate revoked
  /acme/key-change:
    post:
      operationId: keyChange
      summary: Roll over the account key
      description: Perform an account key rollover.
      tags:
        - Account
      requestBody:
        required: true
        content:
          application/jose+json:
            schema:
              $ref: '#/components/schemas/JwsRequest'
      responses:
        '200':
          description: Key rolled over
components:
  schemas:
    JwsRequest:
      type: object
      description: A JSON Web Signature (JWS) flattened serialization object.
      properties:
        protected:
          type: string
          description: Base64url-encoded JWS Protected Header.
        payload:
          type: string
          description: Base64url-encoded payload.
        signature:
          type: string
          description: Base64url-encoded JWS signature.
      required:
        - protected
        - payload
        - signature
      additionalProperties: true
    GenericResponse:
      type: object
      additionalProperties: true