This documentation applies to the SSLMate for SaaS service. If you are using SSLMate Basic, please see the APIv2 reference instead.

The SSLMate API uses REST principles. You make HTTP requests to predictable, resource-oriented URLs using standard HTTP verbs and HTTP authentication. Resources are uploaded as JSON objects. All responses, including errors, are JSON objects. Requests and responses use the UTF-8 character encoding.

Feel free to get in touch if you have any questions or need help using the API. SSLMate is happy to help!

Include your API key in the HTTP Authorization header as an OAuth2 Bearer token. To get an API key, visit your account's API keys page. The API key must have either "Order and Manage Certificates" or "Full Access" permissions.

If your HTTP stack does not support authenticating with a Bearer token, you can authenticate using traditional HTTP Basic Authentication instead, by sending your API key as the username and leaving the password empty.

To facilitate testing, SSLMate operates a sandbox website at https://sandbox.sslmate.com, with its own API endpoint (shown to the right). Certificates acquired on the sandbox site are free and are signed by an untrusted testing certificate authority.

The sandbox website uses its own user account database, so you must sign up for a separate account on the sandbox site. Your sandbox API credentials are available on your account page on the sandbox site.

Object fields marked "expandable" are not included in responses by default, but can be included by passing the name of the field in the expand parameter to the query string of the request.

The expand parameter is available for all API requests, and applies to the response to that request only. You can expand fields of nested objects using the dot character. For example, expanding current_cert.leaf on an order will expand the current_cert field into a certificate object, and then expand the certificate's leaf field.

You can expand multiple fields by specifying the expand parameter multiple times. The expand parameter is always passed in the query string, even for POST requests.

Responses that contain multiple items may be paginated. When additional items are available, the response's HTTP Link header contains a "next" relation specifying the URL (which may be relative) of the next page.

When an order's cluster field is null, the order is unmanaged. You are responsible for generating keys and CSRs and installing certificates on your servers after they are issued. You must provide the CSR in the order's csr field.

When an order's cluster field is non-null, the order is managed by the corresponding sslmate-agent cluster. sslmate-agent will automatically generate keys and CSRs and install certificates on all the servers belonging to the cluster. You must not set the order's csr field. You must install sslmate-agent on your servers. See the sslmate-agent guide for details.

To create an order, POST a JSON-encoded order object to the orders endpoint (/api/v3/orders). The object must contain the dns_names field with at least one DNS name. If the order is to be managed by an sslmate-agent cluster, be sure to include the cluster field. If the order is not to be managed by sslmate-agent, be sure to include the csr field.

Creating an order may incur charges depending on the order's product type.

A successful response contains the newly created order object, as JSON.

To update an order, POST an order object to the order's URL (/api/v3/orders/ORDER_NAME). All fields in the object are optional. If a field is omitted, the current value is preserved.

Updating an order may incur charges depending on the order's product type.

A successful response contains the updated order object, as JSON.

To retrieve an order, GET its URL (/api/v3/orders/ORDER_NAME).

A successful response contains the order object, as JSON.

To delete an order, DELETE its URL (/api/v3/orders/ORDER_NAME).

A successful response is an empty body with HTTP status 204.

To list all orders in your account, GET the orders endpoint (/api/v3/orders).

The following optional parameters may be passed in the query string:

A successful response contains a JSON array of order objects.

You can configure SSLMate to invoke a webhook whenever an order's current certificate changes. SSLMate POSTs the order object with the following fields expanded:

• current_cert.leaf
• current_cert.chain
• current_cert.root

Visit your webhooks page to add a webhook endpoint.

Sectigo

If the product is sectigo, then the CSR provided in the csr field must satisfy the following requirements:

• The public key must use one of the following algorithms:

  • If the order's key_type field contains "rsa":
    • 2048 bit RSA
    • 3072 bit RSA
    • 4096 bit RSA
  • If the order's key_type field contains "ecdsa":
    • NIST P-256 (secp256r1 / prime256v1) ECDSA
    • NIST P-284 (secp384r1) ECDSA

Note that the common name and SANs in the CSR are completely ignored.

Let's Encrypt

If the product is lets_encrypt, then the CSR provided in the csr field must satisfy the following requirements:

• The public key must use one of the following algorithms:

  • If the order's key_type field contains "rsa":
    • 2048 bit RSA
    • 3072 bit RSA
    • 4096 bit RSA
  • If the order's key_type field contains "ecdsa":
    • NIST P-256 (secp256r1 / prime256v1) ECDSA
    • NIST P-284 (secp384r1) ECDSA

• The common name (CN), if present, must equal one of the DNS names in the order object.

• The subject alternative name extension must contain the exact same DNS names as the order object (not necessarily in the same order).

The following openssl command generates a 2048 bit RSA key, writing the private key to the file named example.com.key:

The following openssl command generates a CSR for the private key in example.com.key, and the DNS names example.com, www.example.com, and mail.example.com. The command outputs the base64-encoded CSR (suitable for the csr field) to standard output. The CSR works with all product types.

The following openssl command reads an existing PEM-encoded CSR from the file named example.com.csr and writes a base64-encoded CSR (suitable for the csr field) to standard output:

To retrieve a certificate, GET its URL (/api/v3/orders/ORDER_NAME/certs/ID). A successful response contains the certificate object, as JSON.

To list all certificates for an order, GET the order's certs endpoint (/api/v3/orders/ORDER_NAME/certs). A successful response contains a JSON array of certificate objects.

The following command reads a base64-encoded DER certificate (as encoded in the leaf, chain, and root fields) from standard input, and writes a PEM-encoded certificate (which is typically used by Linux applications) to standard output: