Let's Encrypt

Supascale integrates with Let's Encrypt for free, automated SSL certificates.

Prerequisites

• Domain bound to your project
• DNS pointing to your server
• Port 80 accessible (for HTTP-01 challenge)

Obtain Certificate via Web UI

1. Click on a project with a domain configured
2. Go to Certificate tab
3. Click Obtain Let's Encrypt Certificate
4. Enter your email address
5. Select challenge type
6. Click Obtain Certificate

Obtain Certificate via API

curl -X POST https://supascale.example.com/api/v1/projects/my-project/certificate/obtain \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "challengeType": "http-01",
    "autoRenew": true
  }'

Response:

{
  "success": true,
  "certificate": {
    "domain": "api.example.com",
    "issuedAt": "2026-01-19T12:00:00Z",
    "expiresAt": "2026-04-19T12:00:00Z",
    "issuer": "Let's Encrypt",
    "autoRenew": true
  }
}

Challenge Types

HTTP-01 (Default)

The simplest method - Let's Encrypt verifies domain ownership via HTTP.

Requirements:

• Port 80 accessible from internet
• No special DNS configuration

Process:

1. Let's Encrypt requests http://yourdomain/.well-known/acme-challenge/token
2. Supascale responds with validation
3. Certificate issued

{
  "challengeType": "http-01"
}

DNS-01

Verify domain ownership via DNS TXT records. Supports wildcards.

Requirements:

• Access to DNS provider API
• DNS provider credentials

Supported DNS Providers:

Example with Cloudflare:

{
  "challengeType": "dns-01",
  "dnsProvider": "cloudflare",
  "dnsCredentials": {
    "apiToken": "your-cloudflare-api-token"
  }
}

Example with AWS Route 53:

{
  "challengeType": "dns-01",
  "dnsProvider": "aws",
  "dnsCredentials": {
    "accessKeyId": "AKIAXXXXXXXX",
    "secretAccessKey": "your-secret-key",
    "region": "us-east-1"
  }
}

Certificate Options

Key Type

{
  "keyType": "ec"
}

Key Size (RSA only)

{
  "keyType": "rsa",
  "keySize": 4096
}

Staging Mode

Test certificate issuance without rate limits:

{
  "staging": true
}

Staging certificates are not trusted by browsers. Only use for testing.

Auto-Renewal

Enable automatic certificate renewal:

{
  "autoRenew": true
}

Supascale checks certificates daily and renews when:

• Less than 30 days until expiration
• Auto-renew is enabled

Manual Renewal

Via Web UI

1. Go to project Certificate tab
2. Click Renew Certificate
3. Wait for confirmation

Via API

curl -X POST https://supascale.example.com/api/v1/projects/my-project/certificate/renew \
  -H "X-API-Key: your-api-key"

Check Certificate Status

Via API

curl https://supascale.example.com/api/v1/projects/my-project/certificate/status \
  -H "X-API-Key: your-api-key"

Response:

{
  "status": "valid",
  "domain": "api.example.com",
  "expiresAt": "2026-04-19T12:00:00Z",
  "daysUntilExpiry": 90,
  "autoRenew": true,
  "lastRenewAttempt": null
}

Revoke Certificate

If your private key is compromised:

curl -X POST https://supascale.example.com/api/v1/projects/my-project/certificate/revoke \
  -H "X-API-Key: your-api-key"

Revoked certificates cannot be un-revoked. You'll need to obtain a new certificate.

Rate Limits

Let's Encrypt has rate limits:

Use staging mode for testing to avoid hitting limits.

Troubleshooting

HTTP-01 Challenge Failed

1. Verify port 80 is accessible: curl http://yourdomain.com
2. Check firewall allows port 80
3. Verify web server is running
4. Check domain DNS is correct

DNS-01 Challenge Failed

1. Verify DNS credentials are correct
2. Check DNS API permissions
3. Wait for DNS propagation (may take minutes)
4. Verify TXT record is created

Certificate Not Trusted

1. Ensure using production (not staging)
2. Verify full certificate chain is installed
3. Check certificate matches domain

Auto-Renewal Failed

1. Check certificate status for error message
2. Verify challenge method still works
3. Check DNS credentials haven't expired
4. Review Supascale logs