Skip to main content
The Certificate API allows you to manage SSL/TLS certificates for securing your applications with HTTPS.

​
Create Certificate

curl -X POST "https://your-dokploy-instance.com/api/certificate.create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example.com Certificate",
    "certificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    "certificateChain": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "serverId": "server_123"
  }'
Upload a custom SSL/TLS certificate for use with your applications.

​
Body Parameters

​
name
string
required
A descriptive name for the certificate (e.g., “example.com SSL”).
​
certificateData
string
required
The PEM-encoded certificate data, including the full certificate chain.
​
privateKey
string
required
The PEM-encoded private key for the certificate. This is stored securely and encrypted.
​
certificateChain
string
The PEM-encoded intermediate certificate chain (if applicable).
​
serverId
string
The ID of the server where this certificate should be deployed. Required for cloud deployments.
Certificate private keys are encrypted at rest and transmitted securely. Ensure you’re using HTTPS when making API calls.

​
Get Certificate

curl -X GET "https://your-dokploy-instance.com/api/certificate.one?certificateId=cert_123" \
  -H "Authorization: Bearer YOUR_API_KEY"
Retrieve details of a specific SSL certificate.

​
Query Parameters

​
certificateId
string
required
The ID of the certificate to retrieve.

​
Response

Returns certificate details including:
  • Certificate name and ID
  • Expiration date
  • Common name (CN) and subject alternative names (SANs)
  • Issuer information
  • Associated server ID
The private key is never returned in API responses for security reasons.

​
List All Certificates

curl -X GET "https://your-dokploy-instance.com/api/certificate.all" \
  -H "Authorization: Bearer YOUR_API_KEY"
Get all SSL certificates in your organization.

​
Response

Returns an array of certificate objects, each containing:
  • Certificate ID and name
  • Expiration date
  • Status (valid, expiring soon, expired)
  • Associated domains
  • Server assignment

​
Remove Certificate

curl -X POST "https://your-dokploy-instance.com/api/certificate.remove" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "certificateId": "cert_123"
  }'
Delete an SSL certificate from your organization.

​
Body Parameters

​
certificateId
string
required
The ID of the certificate to remove.
Before removing a certificate, ensure no applications are currently using it. Deleting an active certificate will cause HTTPS errors for associated domains.

​
Certificate Management Best Practices

​
Certificate Formats

Dokploy accepts PEM-encoded certificates. Common file extensions include:
  • .pem - Privacy Enhanced Mail format
  • .crt or .cer - Certificate files
  • .key - Private key files

​
Converting Other Formats

If you have certificates in other formats, convert them to PEM: From DER to PEM: 
openssl x509 -inform der -in certificate.cer -out certificate.pem
From PKCS#12 (.pfx/.p12) 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 privatekey.pem

​
Certificate Chain Order

When providing a certificate chain, ensure proper order:
  1. Your domain certificate (leaf)
  2. Intermediate certificate(s)
  3. Root certificate (optional)

​
Security Considerations

Certificate Security
  • Never commit certificates or private keys to version control
  • Use strong encryption for private keys
  • Rotate certificates before expiration
  • Monitor certificate expiration dates
  • Use automated certificate management when possible (e.g., Let’s Encrypt)

​
Let’s Encrypt Integration

For automatic certificate management:
  • Dokploy supports automatic Let’s Encrypt certificate generation
  • Certificates auto-renew before expiration
  • No manual upload required for standard domains
  • Use custom certificates only for:
    • Wildcard certificates (if not using DNS validation)
    • Internal CA certificates
    • Specific compliance requirements

​
Monitoring Certificate Expiration

Regularly check certificate status:
  1. List all certificates to see expiration dates
  2. Set up alerts for certificates expiring within 30 days
  3. Plan renewal or replacement before expiration

​
Common Use Cases

​
Wildcard Certificates

Use a single certificate for multiple subdomains: 
# Certificate for *.example.com
curl -X POST "https://your-dokploy-instance.com/api/certificate.create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wildcard example.com",
    "certificateData": "...",
    "privateKey": "..."
  }'
This certificate can secure:
  • app.example.com
  • api.example.com
  • staging.example.com
  • Any subdomain under example.com

​
Multi-Domain Certificates (SAN)

Single certificate for multiple specific domains: 
# Certificate for example.com, www.example.com, api.example.com
curl -X POST "https://your-dokploy-instance.com/api/certificate.create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Multi-domain Certificate",
    "certificateData": "...",
    "privateKey": "..."
  }'

​
Internal CA Certificates

For private networks or development environments: 
# Upload internal CA certificate
curl -X POST "https://your-dokploy-instance.com/api/certificate.create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Internal CA Certificate",
    "certificateData": "...",
    "privateKey": "...",
    "certificateChain": "..."
  }'

​
Error Handling

​
Common Error Responses

Invalid Certificate Format 
{
  "error": "Invalid certificate",
  "message": "The provided certificate is not in valid PEM format"
}
Certificate/Key Mismatch 
{
  "error": "Key mismatch",
  "message": "The private key does not match the certificate"
}
Expired Certificate 
{
  "error": "Certificate expired",
  "message": "The certificate has already expired and cannot be used"
}
Certificate In Use 
{
  "error": "Certificate in use",
  "message": "Cannot delete certificate as it is currently used by active applications"
}