Endpoints
List certificates
GET /apps/{app_name}/certificates
List all certificates for an app, with optional filtering and cursor-based pagination.
Path parameters
Query parameters
GET/v1/apps/{app_name}/certificates
Status: 200 OK - Example response
Request ACME certificate
POST /apps/{app_name}/certificates/acme
Add a hostname to your app and request an automatic Let’s Encrypt certificate. Fly.io will attempt to validate domain ownership and issue a certificate. Check the dns_requirements in the response to see what DNS records you need to configure.
Path parameters
Body parameters
POST/v1/apps/{app_name}/certificates/acme
Status: 201 created - Example response
Import custom certificate
POST /apps/{app_name}/certificates/custom
Upload your own certificate and private key in PEM format. The certificate must not be expired, the private key must match the certificate, and the hostname must appear in the certificate’s Subject Alternative Names (SAN) or Common Name (CN). Wildcard certificates are supported.
Domain ownership must be verified via a _fly-ownership DNS TXT record before the certificate becomes active. Check the dns_requirements.ownership field in the response for the required record.
Path parameters
Body parameters
POST/v1/apps/{app_name}/certificates/custom
Status: 201 created - Example response
Get certificate details
GET /apps/{app_name}/certificates/{hostname}
Get detailed information about a hostname’s certificates, including validation status, DNS requirements, and any validation errors.
For wildcard hostnames, URL-encode the * character (e.g. %2A.example.com).
Path parameters
GET/v1/apps/{app_name}/certificates/{hostname}
Status: 200 OK - Example response
Check certificate status
POST /apps/{app_name}/certificates/{hostname}/check
Trigger a fresh DNS validation check for a hostname. Returns the same details as the get endpoint, plus actual DNS records resolved for the hostname. Use this to diagnose DNS configuration issues.
Path parameters
POST/v1/apps/{app_name}/certificates/{hostname}/check
Status: 200 OK - Example response
Delete hostname and all certificates
DELETE /apps/{app_name}/certificates/{hostname}
Remove a hostname and all associated certificates (both ACME and custom) from the app.
Path parameters
DELETE/v1/apps/{app_name}/certificates/{hostname}
Status: 204 no content
Delete ACME certificates
DELETE /apps/{app_name}/certificates/{hostname}/acme
Stop ACME certificate issuance for a hostname. If a custom certificate exists, it will continue to be served. The hostname itself is not removed.
Path parameters
DELETE/v1/apps/{app_name}/certificates/{hostname}/acme
Status: 200 OK - Example response
Delete custom certificate
DELETE /apps/{app_name}/certificates/{hostname}/custom
Remove the custom certificate for a hostname. If ACME certificates are configured, they will continue to be served. The hostname itself is not removed.
Path parameters
DELETE/v1/apps/{app_name}/certificates/{hostname}/custom
Status: 200 OK - Example response