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
You authenticate to the SSLMate API by providing your API key in the HTTP Authorization header as an OAuth2 Bearer token. Your API key can be found on your account page,
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
SSLMate uses HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error with the request, and codes in the 5xx range indicate an error 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.
If the field is a child of another field, the field names are
separated by a dot. For example, identifiers.0.approval indicates a problem with the
approval field of the 0th element of the identifiers array.
|
| 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
Some objects contain fields marked "expandable." These fields 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 add it to the order.
Orders can be modified after they are created should your requirements change; for example, if you need to certify a different 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 add it to 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 add it to 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 must approve every DNS name before the certificate is issued, by publishing a special DNS record, adding a rule to your web server, or manually over email. Adding or removing a DNS name automatically resets the order's csr field to null. If the order is unmanaged, you must also provide a new CSR containing the new DNS names. (If the order is managed, sslmate-agent provides a new CSR for you.) SSLMate will issue a new certificate securing the new set of DNS names. 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. Although DNS names need not be publicly accessible, 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 |
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 are using 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. 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 to which the order now belongs. |
| 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. |
| 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. |
| renewal_product string or null | Still under development. Do not include this field when creating an order. |
| 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. Defaults to "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. The CSR's common name must contain the order's first DNS name, and the CSR's subject alternative name (SAN) extension must contain all the order's DNS names (including the first). See the CSR Requirements section for details. |
| revision integer |
A positive, non-zero integer which increases 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.
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.
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
The CSR provided in the csr parameter 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 country (C) must be a valid two-letter ISO country code (e.g.
US). Exactly one C attribute must be present. -
The common name (CN) must be the same as the first DNS name in order object. Exactly one CN attribute must be present.
-
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 shell script uses the openssl command to generate a conformant CSR
for private key in the file named example.com.key, and the DNS names
example.com, www.example.com, and mail.example.com. The script outputs
the base64-encoded CSR (suitable for the csr field) to standard output.
The parts you should modify are in bold.
#!/bin/sh
(openssl req -new -key example.com.key -config /dev/stdin -outform DER | openssl enc -base64 | tr -d '\n') <<-!
[req]
prompt = no
default_md = sha256
distinguished_name = subject
req_extensions = extensions
[subject]
C = US
CN = example.com
[extensions]
subjectAltName = DNS:example.com, DNS:www.example.com, DNS:mail.example.com
!
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 enc -base64 | tr -d '\n'
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. The first DNS name is in the certificate's common name field. All DNS names (including the first) are in the certificate's subject alternative name (SAN) extension. 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 key certified by this certificate. Read-only |
| cluster string or null | The name of the sslmate-agent cluster which created the key certified by this certificate. Null if it was created manually. 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:
base64 --decode | openssl x509 -inform DER