Introduction
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!
API Endpoint
https://sslmate.com/api/v3
Authentication
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.
Example Request
Sandbox
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.
Sandbox API Endpoint
https://sandbox.sslmate.com/api/v3
Errors
The HTTP response code indicates the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a problem with the request, and codes in the 5xx range indicate a problem with SSLMate's servers. An error object is returned by the server for any unsuccessful request.
The error object
Attributes
| code string | A short machine-readable code that describes the error. The meaning of an error code will never change, although SSLMate may define additional error codes in the future. |
|---|---|
| message string | A human-readable message. The value of this field is only suitable for human consumption; the exact wording of messages may change without notice. For a machine-readable code, use the code field. |
| field string | The name of the request field that caused the error. Only present if the error is field-specific. |
| sub_errors array | An array of error objects that describe the problem(s) which caused this error in greater detail. Only present for some error types. Sub-errors do not have further sub-errors. |
Example error
Expanding objects
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.
Example Request
Pagination
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.
Example Link Header
Orders
An order specifies what you need in a certificate: the domain names, the product type, and the public key (via a CSR). The first step to obtaining a certificate is to create an order. SSLMate will asynchronously issue a certificate matching your specification and associate it with the order.
Orders can be modified after they are created should your requirements change; for example, if you need to generate a new key or add additional DNS names. Orders can be modified even if a certificate has already been issued. Just modify the existing order, and SSLMate will automatically issue a new certificate matching your updated specification and associate it with the existing order.
You do not need to create a new order before the certificate expires. If auto-renew is enabled, SSLMate will automatically issue a new certificate before expiration and associate it with the existing order.
You can retrieve issued certificates by polling the API, or SSLMate can push them to you via webhook. If the order is managed, sslmate-agent will automatically retrieve and install new certificates on your servers.
The order object
Attributes
| name string |
The name of the order, used to reference the order in the API and CLI, and in filenames related to the order. The order name does not appear in the certificate and does not need to be a valid DNS name, but by convention it is usually the same as the order's first DNS name. If you omit this field when creating an order, it defaults to the first DNS name. The order name cannot be changed after an order has been created. Read-only |
|---|---|
| dns_names array |
A list of DNS names that you need your certificate to secure. A DNS name can be a domain (e.g. example.com), a sub-domain (e.g. www.example.com, mail.corp.example.com), or a wildcard (e.g. *.example.com). At least one DNS name must be specified. You can create an order for any DNS name at any time, but you must approve every DNS name before the certificate will be issued, by publishing a special DNS record, adding a rule to your web server, or manually over email. If the order's product type requires the CSR to include every DNS name (see CSR Requirements), then adding or removing a DNS name will automatically reset the order's csr field to null. If the order is unmanaged, you will need to provide a new CSR. If the order is managed, sslmate-agent will generate a new CSR automatically. Adding DNS names to an existing order may cause your account to be billed if the product type is priced by number of DNS names. DNS names do not need to be publicly accessible, but they must be part of a public domain. For example, internal.example.com is OK because example.com is a public domain, but localhost and server.internal are not OK because they are not part of a public domain. |
| approver_emails object |
An object specifying email addresses for DNS names that are manually approved over email. Place the DNS name in the member name and the email address in the member value. Example: {
"example.com": "admin@example.com",
"www.example.com": "admin@example.com"
}
You only need to specify an approver email address for DNS names that are not automatically approved using DNS or HTTP approval. If you use exclusively DNS or HTTP approval, you can disregard the approver_emails field. Email-based approval is only supported by the "sectigo" product. |
| cluster string or null |
The name of the sslmate-agent cluster which manages the order, or null if the order is unmanaged. See order management for details. The default is null. Changing this field automatically resets the order's csr field to null. If the order is now unmanaged, you must generate a new key and provide a new CSR. If the order is managed, this will be done by the sslmate-agent cluster which now manages the order. |
| auto_renew bool |
When true, SSLMate will automatically issue a new certificate for this order before the current certificate expires. When false, SSLMate only issues a new certificate when you explicitly change one of the order's parameters. To manually renew when auto-renew is disabled, change auto_renew is true and then immediately change it back to false. The default value for auto_renew is true. Auto-renewal is highly recommended. |
| muted bool |
When false (the default), SSLMate emails you expiration notices 30 days, 14 days, 7 days, 3 days, and 1 day prior to expiration if the order's current certificate is expiring. When true, SSLMate does not notify you if the order's current certificate is expiring. |
| paused bool |
When true, SSLMate will not issue any certificates for this order, even if you modify the order or if the current certificate is expiring. Defaults to false. |
| product string |
Either "lets_encrypt" for a free 90 day certificate issued by Let's Encrypt, or "sectigo" for a paid 1 year certificate issued by Sectigo. Changing the product will automatically reset the order's csr field to null if the new product does not support the existing CSR (see CSR Requirements for details). If the order is unmanaged, you will need to provide a new CSR. If the order is managed, the sslmate-agent cluster will generate a new CSR automatically. |
| key_type string |
Key type ("rsa" or "ecdsa") to use for this order. Changing this field automatically resets the order's csr field to null. If the order is unmanaged, you must generate a new private key of the correct type and provide a new CSR for the new key. If the order is managed, sslmate-agent does this for you. If you omit the key_type field but include csr, key_type will default to the type of the CSR's key. Otherwise, the default is "rsa". |
| csr string or null |
The DER-encoded PKCS#10 certificate signing request (CSR) for the key you want to certify, transmitted as base64 with no line breaks. Only specify this field if the order is unmanaged. If the order is managed, omit this field and let sslmate-agent generate the CSR for you. Different product types have their own requirements for the CSR. See the CSR Requirements section for details. |
| revision integer |
A positive, non-zero integer which increases by at least 1 every time this order is modified. This field is read-only and is set by SSLMate. Read-only |
| current_cert object or null |
The certificate object for the order's current certificate. Null if the order has no current certificate.
The current certificate is the best certificate for the order.
When SSLMate issues a new certificate (e.g. because the current one is expiring soon, or
you've changed the order's DNS names), this field is updated. If the order is
unmanaged, you should
periodically retrieve the order object, with |
| current_cert_download string |
A public URL from which you can download the order's current certificate, plus chain, as a sequence of PEM-encoded X.509 certificates. The URL stays the same even as the current certificate changes and does not require authentication. If the order doesn't have a current certificate, the URL returns an empty response with HTTP code 202. This field is read-only and is set by SSLMate. Read-only |
Example order
Order Management
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.
Create an Order
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.
Example Order Creation
Update an Order
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.
Example Order Update (Modify DNS Names)
Retrieve an Order
To retrieve an order, GET its URL (/api/v3/orders/ORDER_NAME).
A successful response contains the order object, as JSON.
Example Order Retrieval
Delete an Order
To delete an order, DELETE its URL (/api/v3/orders/ORDER_NAME).
A successful response is an empty body with HTTP status 204.
Example Order Deletion
List Orders
To list all orders in your account, GET the orders endpoint (/api/v3/orders).
A successful response contains a JSON array of order objects.
Example Order List Retrieval
Order Webhook
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.leafcurrent_cert.chaincurrent_cert.root
Visit your webhooks page to add a webhook endpoint.
CSR Requirements
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
- If the order's key_type field contains "rsa":
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
- If the order's key_type field contains "rsa":
-
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).
Key and CSR Generation
The following openssl command generates a 2048 bit RSA key, writing the private key
to the file named example.com.key:
openssl genpkey -out example.com.key -algorithm rsa -pkeyopt rsa_keygen_bits:2048
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.
openssl req -new -key example.com.key -nodes -subj / -addext subjectAltName=DNS:example.com,DNS:www.example.com,DNS:mail.example.com -outform DER | openssl base64 -A
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:
openssl req -in example.com.csr -outform DER | openssl base64 -A
Certificates
The certificate object represents a certificate and its metadata. When a certificate is issued, SSLMate automatically creates a certificate object and associates it with the corresponding order.
The certificate object
Attributes
| id integer | The ID of the certificate, used to reference the certificate in the API. SSLMate assigns the ID automatically. Read-only |
|---|---|
| state string |
One of the following values:
|
| current bool |
True if this is the order's best certificate. At most one certificate per order has this field set to true. |
| dns_names array |
The DNS names present in this certificate's subject alternative name (SAN) extension (not necessarily in the same order). At most one of these DNS names will be also be in the certificate's common name field. Read-only |
| expiration string | The date and time, in RFC3339 format, when this certificate expires. Read-only |
| not_before string | The date and time, in RFC3339 format, when this certificate became valid. This time is always in the past. Read-only |
| sha256 string | The SHA-256 fingerprint of the DER-encoded leaf certificate, as lowercase hex. Read-only |
| key_type string | The type ("rsa" or "ecdsa") of certificate's key. Read-only |
| pubkey_sha256 string | The SHA-256 fingerprint of the certificate's DER-encoded public key, as lowercase hex. Read-only |
| leaf string | The DER-encoded leaf certificate, transmitted in base64 with no line breaks. Read-only |
| chain array | An array of DER-encoded chain certificates, transmitted in base64 with no line breaks. The first certificate certifies the leaf certificate, and each subsequent certificate certifies the one before it. Read-only |
| root string | The DER-encoded root certificate, transmitted in base64 with no line breaks. This certificate certifies the last certificate in the chain array, or the leaf certificate if chain is empty. Read-only |
Example certificate
Retrieve a Certificate
To retrieve a certificate, GET its URL (/api/v3/orders/ORDER_NAME/certs/ID).
A successful response contains the certificate object, as JSON.
Example Certificate Retrieval
Example Response
See certificate object.
List Certificates
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.
Example Certificate List Retrieval
Certificate Conversion
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:
openssl base64 -A -d | openssl x509 -inform DER