Custom Certificates

By default, SaaS Custom Domains gets a certificate for every custom domain automatically. If a domain needs a certificate from a specific certificate authority, for example your customer's own DigiCert account, upload it as a custom certificate. On this page, we'll look at how to upload, list, retrieve, and delete custom certificates.

Custom certificates are enabled per account. Contact support to enable them for yours.

The proxy serves a custom certificate for the names it covers, from the time you upload it until it expires or you delete it. Changes reach the proxy within 10 minutes.

Renewing a certificate

Custom certificates aren't renewed automatically. Before one expires, get a new certificate from your certificate authority and replace the old one:

Upload the new certificate.
Delete the old certificate. Until you do, the proxy can keep serving the old one while it's still valid.

To automate this, call these two endpoints from your ACME client's deploy hook, or use scd certificates create and scd certificates delete. This works with any certificate authority, including ones that need External Account Binding (EAB), such as DigiCert, because your ACME client talks to the certificate authority and only the finished certificate is uploaded.

The custom certificate model

The custom certificate model contains all the information about your custom certificates.

Properties

Name
uuid
Type
string
Description
Unique identifier for the custom certificate.
Name
expires_at
Type
timestamp
Description
The expiration date and time of the certificate.
Name
not_before
Type
timestamp
Description
The date and time before which the certificate is not valid.
Name
fingerprint
Type
string
Description
The fingerprint of the certificate, used for verification.
Name
issuer
Type
string
Description
The issuer of the certificate, containing information about the certificate authority.
Name
public_key_sha
Type
string
Description
The SHA-256 hash of the public key.
Name
sans
Type
array
Description
An array of Subject Alternative Names (SANs) included in the certificate.
Name
serial_number
Type
string
Description
The serial number of the certificate.
Name
signature_algorithm
Type
string
Description
The algorithm used to sign the certificate.
Name
subject
Type
string
Description
The subject of the certificate, containing information about the entity the certificate belongs to.
Name
created_at
Type
timestamp
Description
The date and time when the certificate was created in SaaS Custom Domains.

GET

/api/v1/accounts/:account_uuid/custom_certificates

Retrieve all

This endpoint allows you to retrieve a paginated list of all custom certificates belonging to an account. By default, 20 custom certificates are shown per page.

Optional attributes

Name
page
Type
integer
Description
The page number to retrieve. Default value is 1.
Name
per_page
Type
integer
Description
The number of items to retrieve per page. Default value is 20.

Request

GET

/api/v1/accounts/:account_uuid/custom_certificates

curl -G https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/custom_certificates \
  -H "Authorization: Bearer {token}" \
  -d page=7

Response

{
  "data": [
    {
      "uuid": "cert_1",
      "expires_at": "2098-12-31T18:00:00.000-06:00",
      "not_before": "2019-12-31T18:00:00.000-06:00",
      "fingerprint": "abcdef1234567890abcdef1234567890abcdef12",
      "issuer": "CN=Example CA, O=Example Org, C=US",
      "public_key_sha": "abcdef1234567890abcdef1234567890abcdef12",
      "sans": ["example.com", "www.example.com"],
      "serial_number": "1234567890",
      "signature_algorithm": "sha256WithRSAEncryption",
      "subject": "CN=example.com, O=Example Org, C=US",
      "created_at": "2024-07-19T04:48:27.000-05:00"
    },
    {
      "uuid": "cert_2",
      // ...
    },
    // ...
  ],
  "pagination": {
    "page": 7,
    "count": 322
  }
}

POST

/api/v1/accounts/:account_uuid/custom_certificates

Create

This endpoint uploads a certificate and its private key. Send both as strings in a JSON body, or as files in a multipart form. It requires an active subscription and custom certificates enabled for the account.

The certificate must already be valid and must not expire within 7 days. RSA and ECDSA keys are supported.

Required attributes

Name
certificate
Type
string
Description
The certificate in PEM format, followed by its intermediate certificates (the full chain, often called fullchain.pem). The certificate for your domain must come first.
Name
private_key
Type
string
Description
The certificate's private key in PEM format (PKCS#1, SEC1 or PKCS#8), without a passphrase.

Request

POST

/api/v1/accounts/:account_uuid/custom_certificates

curl https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/custom_certificates \
  -H "Authorization: Bearer {token}" \
  -F certificate=@fullchain.pem \
  -F private_key=@privkey.pem

Response

{
  "uuid": "cert_4d1867c3",
  "expires_at": "2027-03-01T23:59:59.000-06:00",
  "not_before": "2026-11-10T00:00:00.000-06:00",
  "fingerprint": "d07d1cf51e45597f20cfcc24d552c9cc6d5eb668b6087f7cab20b2d83991ec8c",
  "issuer": "/C=US/O=DigiCert Inc/CN=DigiCert Global G2 TLS RSA SHA256 2020 CA1",
  "public_key_sha": "08259821b0ebb20ca4bdeda5e04fd53e936e896c154ddff5cb544efb1a6820e1",
  "sans": ["app.customer.com", "www.app.customer.com"],
  "serial_number": "18446051721245871",
  "signature_algorithm": "sha256WithRSAEncryption",
  "subject": "/CN=app.customer.com",
  "created_at": "2026-11-10T15:13:03.189-06:00"
}

GET

/api/v1/accounts/:account_uuid/custom_certificates/:certificate_uuid

Retrieve

This endpoint allows you to retrieve a custom certificate by providing its UUID. Refer to the list at the top of this page to see which properties are included with custom certificate objects.

Request

GET

/api/v1/accounts/:account_uuid/custom_certificates/:certificate_uuid

curl https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/custom_certificates/:certificate_uuid \
      -H "Authorization: Bearer {token}"

Response

{
  "uuid": "cert_1",
  "expires_at": "2098-12-31T18:00:00.000-06:00",
  "not_before": "2019-12-31T18:00:00.000-06:00",
  "fingerprint": "abcdef1234567890abcdef1234567890abcdef12",
  "issuer": "CN=Example CA, O=Example Org, C=US",
  "public_key_sha": "abcdef1234567890abcdef1234567890abcdef12",
  "sans": ["example.com", "www.example.com"],
  "serial_number": "1234567890",
  "signature_algorithm": "sha256WithRSAEncryption",
  "subject": "CN=example.com, O=Example Org, C=US",
  "created_at": "2024-07-19T04:48:27.000-05:00"
}

DELETE

/api/v1/accounts/:account_uuid/custom_certificates/:certificate_uuid

Delete

This endpoint deletes a custom certificate. The proxy stops serving it within 10 minutes.

Request

DELETE

/api/v1/accounts/:account_uuid/custom_certificates/:certificate_uuid

curl -X DELETE https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/custom_certificates/:certificate_uuid \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Custom Certificate cert_1 deleted."
}

Error responses

Uploading a certificate fails with 400 Bad Request when the certificate or key isn't usable. The error message says what's wrong, and error_code is one of:

Name
certificate_blank
Type
Description
No certificate was sent.
Name
certificate_invalid
Type
Description
The certificate isn't a PEM-encoded X.509 certificate.
Name
certificate_not_yet_valid
Type
Description
The certificate's validity period hasn't started yet.
Name
certificate_expired
Type
Description
The certificate has expired.
Name
certificate_expires_too_soon
Type
Description
The certificate expires within 7 days.
Name
private_key_blank
Type
Description
No private key was sent.
Name
private_key_invalid
Type
Description
The private key isn't a PEM-encoded RSA or ECDSA key, or it's protected with a passphrase.
Name
private_key_mismatch
Type
Description
The private key doesn't belong to the certificate. Check that the certificate for your domain comes first in certificate.

If custom certificates aren't enabled for the account, the API responds with 403 Forbidden and the error code custom_certificates_not_enabled. Without an active subscription, it responds with 402 Payment Required.

400 Bad Request - Private key does not match

{
  "error": "Private key does not match the certificate's public key",
  "error_code": "private_key_mismatch"
}

403 Forbidden

{
  "error": "Custom Certificates aren't enabled for this account. Contact support to enable them.",
  "error_code": "custom_certificates_not_enabled"
}

404 Not Found

{
  "error": "Custom Certificate cert_1 not found.",
  "error_code": "not_found"
}