Skip to content

HTTP-01 Challenge API Reference

TL;DR: HTTP-01 challenge API provides standardized endpoints at /.well-known/acme-challenge/ for certificate validation, enabling programmatic integration with ACME servers through simple HTTP GET requests.

Overview

Certificate authorities rely on standardized HTTP-01 challenge endpoints to validate domain ownership during the ACME certificate issuance process. This API reference documents the endpoint structure, integration patterns, and implementation requirements for production environments. Organizations implementing automated certificate management need to understand these endpoints to ensure reliable validation across diverse hosting configurations.

The HTTP-01 challenge API follows RFC 8555 specifications, creating a consistent validation mechanism across all ACME implementations. This standardization enables certificate authorities to perform validation requests without custom integration for each domain. Production teams configure their infrastructure to serve challenge responses from well-known paths, allowing automated certificate issuance to function reliably.

Integration patterns range from simple static file serving to complex enterprise deployments with load balancers and monitoring systems. Understanding the API structure helps teams design robust certificate automation that handles edge cases, monitors validation success rates, and maintains security compliance throughout the certificate lifecycle.

Core Challenge Endpoints

Standard Challenge Path Structure

The HTTP-01 challenge follows a standardized URL pattern defined by the ACME protocol:

http://<DOMAIN>/.well-known/acme-challenge/{token}

This endpoint serves as the primary validation path where Certificate Authorities retrieve challenge responses. The standard format ensures consistency across all ACME implementations.

Domain-Specific Challenge URLs

Each domain validation requires a unique token-based endpoint:

http://{domain}/.well-known/acme-challenge/{token}

The token is dynamically generated during the challenge process and must be accessible via GET request. The challenge system also supports the simplified format:

http://<domain>/.well-known/acme-challenge/token

Production Implementation Examples

Real-World Challenge Endpoints

Educational institutions commonly implement HTTP-01 challenges. For example, the Parkdip School District utilizes:

GET http://helpdesk.parkdip.k12.mo.us:80/.well-known/acme-challenge/V1gs6k9wNsHsWQ9mMDmEIIdyyhFnli56U69wYXBWdZQ

Commercial implementations follow similar patterns, as seen with CrypShark's support system:

GET http://support.crypshark.com:80/.well-known/acme-challenge/WYIbJ1jGmeYVzRuoj4IxqEgv2bTddFEvrDPNTknxrUA

Generic Implementation Pattern

For enterprise deployments, implement the generic challenge endpoint structure:

GET http://x.y.z:80/.well-known/acme-challenge/{token}

This pattern allows Let's Encrypt servers to validate domain control through standardized HTTP-01 challenge verification.

ACME Server Integration

Let's Encrypt API Integration

The official Let's Encrypt ACME v2 API provides challenge endpoints in this format:

https://acme-v02.api.letsencrypt.org/acme/challenge/1C1WRb50QzI7Hd7i8dSYTiqb3L79yHw4tWJIbX8lwHA/12155712672

This endpoint manages the challenge lifecycle and coordinates validation between your server and Let's Encrypt's infrastructure.

Challenge Responder Configuration

ACME client implementations create HTTP-01 challenge responders that listen on port 80 to handle Certificate Authority validation requests. Configure your responder to:

  • Listen on port 80 for incoming challenge requests
  • Serve challenge tokens from the /.well-known/acme-challenge/ directory
  • Respond to GET requests with the appropriate challenge response

HTTP Methods and Protocols

Challenge File Retrieval Process

The validation process establishes an HTTP connection to your server to retrieve challenge files using the http-01 challenge type. The Certificate Authority performs:

GET /{domain}/.well-known/acme-challenge/{token}

Port Requirements

HTTP-01 challenges require specific port configurations:

  • Port 80 (HTTP): Primary challenge validation port
  • Port 443 (HTTPS): Optional secure challenge validation - this port is not part of the HTTP-01 standard but it's used by tls-alpn-01.

Port 80 HTTP challenge verification is mandatory for ACME validation, regardless of whether your production site runs on HTTPS.

Directory Structure Requirements

Challenge Directory Setup

Place challenge files in the /.well-known/acme-challenge/ directory under your website root. This directory must be:

  • Publicly accessible via HTTP GET requests
  • Writable by your ACME client
  • Served without authentication requirements

Alternative Validation Paths

For compliance with CA/B Baseline Requirements, some non-ACME Certificate Authorities also support domain validation through:

/.well-known/pki-validation

This path supports both HTTP and HTTPS methods for enhanced validation flexibility.

Enterprise Integration Patterns

Automated Challenge Response

Configure your web server to automatically serve challenge responses:

location /.well-known/acme-challenge/ {
    root /var/www/challenges;
    try_files $uri =404;
}

Load Balancer Configuration

For enterprise deployments with load balancers, ensure all backend servers can serve challenge files consistently. Configure health checks to verify challenge endpoint availability across all nodes.

Monitoring and Logging

Implement monitoring for challenge endpoints to track:

  • Challenge request frequency
  • Response times for /.well-known/acme-challenge/ paths
  • Failed validation attempts
  • Certificate renewal success rates