openapi: 3.1.0
info:
  title: SSL/TLS Certificate Management Certificates API
  description: A REST API for SSL/TLS certificate lifecycle management including issuance, renewal, revocation, and monitoring. Represents common certificate management capabilities available across major CAs and PKI platforms including Let's Encrypt ACME, DigiCert, Sectigo, and enterprise PKI systems.
  version: '1.0'
  contact:
    name: Let's Encrypt
    url: https://letsencrypt.org/
  license:
    name: Mozilla Public License 2.0
    url: https://mozilla.org/MPL/2.0/
servers:
- url: https://api.certmanager.example.com/v1
  description: Certificate Management API
security:
- ApiKeyAuth: []
tags:
- name: Certificates
  description: Certificate issuance and management
paths:
  /certificates:
    get:
      operationId: listCertificates
      summary: List Certificates
      description: Returns a paginated list of SSL/TLS certificates in the account, including their status, expiry dates, and associated domains.
      tags:
      - Certificates
      parameters:
      - name: status
        in: query
        description: Filter by certificate status
        schema:
          type: string
          enum:
          - issued
          - pending
          - revoked
          - expired
      - name: domain
        in: query
        description: Filter by domain name
        schema:
          type: string
      - name: expiringBefore
        in: query
        description: Filter certificates expiring before this date (ISO 8601)
        schema:
          type: string
          format: date
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: Certificate list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: requestCertificate
      summary: Request Certificate
      description: Initiates a certificate issuance request for one or more domain names. Returns an order object with challenge details for domain validation.
      tags:
      - Certificates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificateRequest'
      responses:
        '201':
          description: Certificate request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateOrder'
        '400':
          $ref: '#/components/responses/BadRequest'
  /certificates/{certificateId}:
    get:
      operationId: getCertificate
      summary: Get Certificate
      description: Returns full details for a specific certificate including PEM data and metadata.
      tags:
      - Certificates
      parameters:
      - $ref: '#/components/parameters/CertificateId'
      responses:
        '200':
          description: Certificate details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate'
        '404':
          $ref: '#/components/responses/NotFound'
  /certificates/{certificateId}/download:
    get:
      operationId: downloadCertificate
      summary: Download Certificate
      description: Downloads the certificate and certificate chain in PEM format. Returns the end-entity certificate and full chain for installation.
      tags:
      - Certificates
      parameters:
      - $ref: '#/components/parameters/CertificateId'
      - name: format
        in: query
        schema:
          type: string
          enum:
          - pem
          - pkcs12
          - der
          default: pem
      responses:
        '200':
          description: Certificate file
          content:
            application/x-pem-file:
              schema:
                type: string
            application/x-pkcs12:
              schema:
                type: string
                format: binary
  /certificates/{certificateId}/renew:
    post:
      operationId: renewCertificate
      summary: Renew Certificate
      description: Initiates certificate renewal for an existing certificate. Uses the same domain list and key unless overridden. Returns a new order object.
      tags:
      - Certificates
      parameters:
      - $ref: '#/components/parameters/CertificateId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reuseKey:
                  type: boolean
                  default: true
      responses:
        '201':
          description: Renewal order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateOrder'
components:
  schemas:
    CertificateOrder:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - pending
          - processing
          - valid
          - invalid
          - expired
        domains:
          type: array
          items:
            type: string
        challenges:
          type: array
          items:
            $ref: '#/components/schemas/Challenge'
        certificateId:
          type: string
          nullable: true
          description: Set when status is valid
        expiresAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
    CertificateListResponse:
      type: object
      properties:
        certificates:
          type: array
          items:
            $ref: '#/components/schemas/Certificate'
        total:
          type: integer
        page:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: string
    Certificate:
      type: object
      properties:
        id:
          type: string
          description: Unique certificate identifier
        commonName:
          type: string
          description: Certificate common name (primary domain)
        subjectAlternativeNames:
          type: array
          items:
            type: string
          description: All SANs in the certificate
        serialNumber:
          type: string
          description: Certificate serial number (hex)
        issuer:
          type: string
          description: Certificate issuer distinguished name
        subject:
          type: string
          description: Certificate subject distinguished name
        notBefore:
          type: string
          format: date-time
          description: Certificate validity start
        notAfter:
          type: string
          format: date-time
          description: Certificate expiry
        status:
          type: string
          enum:
          - issued
          - pending
          - revoked
          - expired
        certType:
          type: string
          enum:
          - DV
          - OV
          - EV
          - wildcard
          - multi-domain
          - private
        pem:
          type: string
          description: PEM-encoded certificate
        chain:
          type: string
          description: PEM-encoded intermediate chain
        keyAlgorithm:
          type: string
          enum:
          - RSA-2048
          - RSA-4096
          - EC-256
          - EC-384
        fingerprint:
          type: object
          properties:
            sha256:
              type: string
            sha1:
              type: string
        createdAt:
          type: string
          format: date-time
        revokedAt:
          type: string
          format: date-time
          nullable: true
        revocationReason:
          type: string
          nullable: true
    Challenge:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - http-01
          - dns-01
          - tls-alpn-01
        domain:
          type: string
        status:
          type: string
          enum:
          - pending
          - processing
          - valid
          - invalid
        token:
          type: string
          description: Challenge token to deploy
        validationRecord:
          type: object
          description: Expected record (URL for http-01, DNS record for dns-01)
    CertificateRequest:
      type: object
      required:
      - domains
      properties:
        domains:
          type: array
          items:
            type: string
          description: Domain names to include in the certificate
        certType:
          type: string
          enum:
          - DV
          - OV
          - EV
          default: DV
        keyAlgorithm:
          type: string
          enum:
          - RSA-2048
          - RSA-4096
          - EC-256
          - EC-384
          default: EC-256
        validityDays:
          type: integer
          description: Certificate validity in days (max 90 for DV, 398 for OV/EV)
          default: 90
        challengeType:
          type: string
          enum:
          - http-01
          - dns-01
          - tls-alpn-01
          default: http-01
        csr:
          type: string
          description: Optional CSR in PEM format (if key is managed client-side)
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    CertificateId:
      name: certificateId
      in: path
      required: true
      description: Certificate identifier
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key