Skip to content
Axelspire Vault

HTTP-01 Challenge API Reference

HTTP-01 challenge API provides standardized endpoints at /.well-known/acme-challenge/ for certificate validation, enabling programmatic integration with ACME servers. This reference documents the endpoint structure, request/response format, and how to implement or debug validation in your environment.

HTTP-01 Challenge API Reference

Section titled “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.

Need help with ACME? Ask Axel Axelspire AI bot with own augmented memory for all ACME/certbot.

Overview

Section titled “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

Section titled “Core Challenge Endpoints”

Standard Challenge Path Structure

Section titled “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

Section titled “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

Section titled “Production Implementation Examples”

Real-World Challenge Endpoints

Section titled “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

Section titled “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

Section titled “ACME Server Integration”

Let’s Encrypt API Integration

Section titled “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

Section titled “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

Section titled “HTTP Methods and Protocols”

Challenge File Retrieval Process

Section titled “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

Section titled “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

Section titled “Directory Structure Requirements”

Challenge Directory Setup

Section titled “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

Section titled “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

Section titled “Enterprise Integration Patterns”

Automated Challenge Response

Section titled “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

Section titled “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

Section titled “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
Section titled “Related Documentation”