> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Certificates

> Configure custom TLS certificates for your domains hosted on Stormkit.

## Overview

By default, Stormkit uses Let's Encrypt to issue certificates automatically for all verified domains. If you want to change this behavior for specific domains, you can configure custom certificates.

This is useful when you:

* Have an existing wildcard certificate
* Need to use certificates from a specific Certificate Authority
* Want to use Extended Validation (EV) certificates
* Have organizational requirements for certificate management

## Configuring Custom Certificates

<Steps>
  <Step title="Navigate to Custom Domains">
    Visit your **Application** > **Environment** > **Custom Domains** page and locate the domain that you'd like to use a custom certificate for.
  </Step>

  <Step title="Access certificate settings">
    Locate the **Expand (...)** button next to the domain and click on it.
  </Step>

  <Step title="Upload certificate">
    Click on **Custom certificate** and provide both:

    * **Certificate** - The SSL certificate in PEM format
    * **Private Key** - The private key used while creating the certificate in PEM format
  </Step>

  <Step title="Save">
    Click save to apply the custom certificate. It will be activated immediately.
  </Step>
</Steps>

<Warning>
  Stormkit accepts only PEM encoded files. If you have certificates in other formats, you'll need to convert them first.
</Warning>

## Certificate Format Requirements

<CardGroup cols={2}>
  <Card title="PEM Format" icon="file-certificate">
    Both certificate and private key must be in PEM (Privacy Enhanced Mail) format, which is Base64 encoded.
  </Card>

  <Card title="Complete Chain" icon="link">
    Include the full certificate chain, including intermediate certificates if applicable.
  </Card>

  <Card title="Matching Key" icon="key">
    The private key must match the certificate. Mismatched keys will cause SSL errors.
  </Card>

  <Card title="Valid Certificate" icon="check">
    Certificate must not be expired and must be valid for the domain you're configuring.
  </Card>
</CardGroup>

## Converting Certificate Formats

### CRT to PEM

If you have a certificate with a `.crt` extension, you can use `openssl` to convert it into PEM format:

```bash theme={null}
openssl x509 -in example_org.crt -out example_org.pem -outform PEM
```

### DER to PEM

```bash theme={null}
openssl x509 -inform der -in example_org.der -out example_org.pem
```

### PKCS12 (PFX) to PEM

To extract the certificate:

```bash theme={null}
openssl pkcs12 -in example_org.pfx -clcerts -nokeys -out example_org.pem
```

To extract the private key:

```bash theme={null}
openssl pkcs12 -in example_org.pfx -nocerts -out example_org.key
```

## Certificate Chain

When uploading your certificate, ensure you include the complete certificate chain:

```text theme={null}
-----BEGIN CERTIFICATE-----
[Your domain certificate]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Intermediate certificate 1]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Intermediate certificate 2]
-----END CERTIFICATE-----
```

## API Access

You can manage custom certificates programmatically using the Stormkit API:

### Upload Custom Certificate

```bash theme={null}
curl -X PUT \
     -H 'Authorization: <api_key>' \
     -H 'Content-Type: application/json' \
     'https://api.stormkit.io/v1/domains/cert' \
     -d '{
       "domainId": "2500",
       "certValue": "-----BEGIN CERTIFICATE-----\n...",
       "certKey": "-----BEGIN PRIVATE KEY-----\n..."
     }'
```

### Delete Custom Certificate

```bash theme={null}
curl -X DELETE \
     -H 'Authorization: <api_key>' \
     'https://api.stormkit.io/v1/domains/cert?id=2500'
```

See the [Domains API documentation](/api/domains) for more details.

## Reverting to Let's Encrypt

To revert to automatic Let's Encrypt certificates:

1. Navigate to **Custom Domains**
2. Find the domain with custom certificate
3. Click the **Expand (...)** button
4. Click **Delete custom certificate**
5. Stormkit will automatically issue a Let's Encrypt certificate

## Security Best Practices

* **Protect private keys** - Never commit private keys to version control
* **Regular renewal** - Monitor certificate expiration dates and renew before expiry
* **Strong key size** - Use at least 2048-bit RSA keys or 256-bit ECC keys
* **Secure storage** - Store certificates and keys in secure, encrypted locations
* **Access control** - Limit who can upload and manage certificates

## Troubleshooting

<AccordionGroup>
  <Accordion title="Certificate upload fails">
    * Verify the certificate is in PEM format
    * Check that the private key matches the certificate
    * Ensure the certificate is valid and not expired
    * Verify the certificate is issued for the correct domain
  </Accordion>

  <Accordion title="SSL errors after upload">
    * Check that you included the complete certificate chain
    * Verify the certificate is valid for the domain
    * Wait a few minutes for the certificate to propagate
    * Clear browser cache and try again
  </Accordion>

  <Accordion title="Private key format issues">
    * Ensure the key is not password protected
    * Convert the key to PEM format if needed
    * Check for proper BEGIN/END markers
  </Accordion>
</AccordionGroup>