Custom Certificates

Use your own SSL certificates from a Certificate Authority (CA) or internal PKI.

When to Use Custom Certificates

• Enterprise CA-issued certificates
• Extended Validation (EV) certificates
• Wildcard certificates from your CA
• Internal/private PKI certificates
• Certificates with specific requirements

Certificate Requirements

Your certificate must:

1. Match the domain - Subject or SAN must include the bound domain
2. Be valid - Not expired, not revoked
3. Include full chain - Include intermediate certificates
4. Have matching private key - Key must match certificate

Prepare Your Files

You'll need:

Combine Certificate Chain

If you have separate files:

# Combine cert and chain
cat domain.crt intermediate.crt root.crt > fullchain.pem

Verify Certificate and Key Match

# Get certificate modulus
openssl x509 -noout -modulus -in certificate.pem | openssl md5

# Get key modulus
openssl rsa -noout -modulus -in private.key | openssl md5

# They should match

Upload via Web UI

1. Click on a project with a domain
2. Go to Certificate tab
3. Click Upload Custom Certificate
4. Paste or upload:
   • Certificate (including chain)
   • Private key
5. Click Upload

Upload via API

curl -X POST https://supascale.example.com/api/v1/projects/my-project/certificate/upload \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----"
  }'

Response:

{
  "success": true,
  "certificate": {
    "domain": "api.example.com",
    "issuedAt": "2026-01-01T00:00:00Z",
    "expiresAt": "2027-01-01T00:00:00Z",
    "issuer": "DigiCert Inc",
    "type": "custom"
  }
}

Validate Certificate

Before uploading, validate your certificate:

curl -X POST https://supascale.example.com/api/v1/projects/my-project/certificate/validate \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate": "-----BEGIN CERTIFICATE-----\n...",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n..."
  }'

Response:

{
  "valid": true,
  "domain": "api.example.com",
  "expiresAt": "2027-01-01T00:00:00Z",
  "issuer": "DigiCert Inc",
  "warnings": []
}

Or with warnings:

{
  "valid": true,
  "warnings": [
    "Certificate expires in less than 30 days"
  ]
}

Certificate Formats

PEM Format (Required)

-----BEGIN CERTIFICATE-----
MIIDrzCCApegAwIBAgIQCDvgVpBCRrGhdWrJWZHHSjANBgkqhkiG9w0BAQUFADBh
...
-----END CERTIFICATE-----

Convert from Other Formats

DER to PEM:

openssl x509 -inform DER -in certificate.der -out certificate.pem

PKCS#12/PFX to PEM:

# Extract certificate
openssl pkcs12 -in certificate.pfx -clcerts -nokeys -out certificate.pem

# Extract private key
openssl pkcs12 -in certificate.pfx -nocerts -nodes -out private.key

PKCS#7 to PEM:

openssl pkcs7 -in certificate.p7b -print_certs -out certificate.pem

Replace Certificate

To replace an existing certificate:

1. Upload new certificate (same process as above)
2. Old certificate is automatically replaced
3. Web server reloads with new certificate

Certificate Renewal Reminders

Custom certificates don't auto-renew. Set reminders:

1. Track expiration dates
2. Set calendar reminders 30 days before expiry
3. Prepare new certificate before expiration
4. Upload replacement before old cert expires

View Certificate Details

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

Response:

{
  "domain": "api.example.com",
  "type": "custom",
  "issuedAt": "2026-01-01T00:00:00Z",
  "expiresAt": "2027-01-01T00:00:00Z",
  "issuer": "DigiCert Inc",
  "subject": "CN=api.example.com",
  "serialNumber": "01:23:45:67:89:AB:CD:EF",
  "fingerprint": "SHA256:..."
}

Remove Certificate

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

Troubleshooting

"Certificate and key don't match"

1. Verify you're using the correct private key
2. Re-export from source if needed
3. Check key hasn't been modified

"Certificate chain incomplete"

1. Include intermediate certificates
2. Order: domain cert → intermediate → root
3. Verify chain: openssl verify -CAfile chain.pem cert.pem

"Certificate doesn't match domain"

1. Check certificate Subject Alternative Names (SAN)
2. Verify domain matches exactly
3. For wildcards, ensure format: *.example.com

Browser Shows Not Secure

1. Verify full chain is uploaded
2. Check certificate isn't expired
3. Verify domain matches exactly
4. Check intermediate certificates are included