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

GET https://sslmate.com/api/v3/orders/example.com Authorization: Bearer 123_Noo5ohpuK6seed5taeku

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

{ "code": "bad_request", "message": "One or more fields in the resource are invalid", "sub_errors": [ { "field": "csr", "code": "unsupported_key_size", "message": "RSA keys must be 2048, 3072, or 4096 bits" } ] }

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

GET https://sslmate.com/api/v3/orders?expand=current_cert.leaf

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

Link: </api/v3/orders?after=example.com>; rel="next"

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.

Expandable
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 expanded, and install the current certificate onto your server if it is different from the already-installed certificate. (Alternatively, you can receive a webhook when the current certificate changes.)

Expandable
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

{ "name": "example.com", "dns_names": ["example.com", "www.example.com"], "approver_emails": {}, "cluster": "webservers", "auto_renew": true, "product": "positivessl", "renewal_product": null, "key_type": "rsa", "revision": 1024, "current_cert_download": "https://certs.sslmate.com/tZwf1MOnfY8AVdXUeHhM/example.com.rsa.pem" }

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

POST https://sslmate.com/api/v3/orders Authorization: Bearer 123_Noo5ohpuK6seed5taeku Content-Type: application/json { "dns_names": ["example.com", "www.example.com"], "cluster": "webservers" }

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)

POST https://sslmate.com/api/v3/orders/example.com Authorization: Bearer 123_Noo5ohpuK6seed5taeku Content-Type: application/json { "dns_names": ["example.com", "www.example.com", "mail.example.com"] }

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

GET https://sslmate.com/api/v3/orders/example.com Authorization: Bearer 123_Noo5ohpuK6seed5taeku

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

DELETE https://sslmate.com/api/v3/orders/example.com Authorization: Bearer 123_Noo5ohpuK6seed5taeku

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

GET https://sslmate.com/api/v3/orders Authorization: Bearer 123_Noo5ohpuK6seed5taeku

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.leaf
  • current_cert.chain
  • current_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
  • 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:

  • valid - the certificate has been issued and can be used.
  • revoked - the certificate was valid but was revoked.
  • expired - the certificate was valid or revoked but has expired.
Read-only
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. Expandable 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. Expandable 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. Expandable Read-only

Example certificate

{ "id": 19334, "state": "valid", "dns_names: ["example.com", "www.example.com"], "not_before": "2017-07-25T19:14:00Z", "not_after": "2017-10-23T19:14:00Z", "sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", "key_type": "rsa", "cluster": "webservers", "leaf": "MIIFODCCBCCgAwIBAgISA5F2oB8pTLQ70sfSG71V+gbPMA0GCSqGSIb3DQEBCwUAME==", "chain": [ "MIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/MS==", "MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA/MS==" ], }

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

GET https://sslmate.com/api/v3/orders/example.com/certs/6201 Authorization: Bearer 123_Noo5ohpuK6seed5taeku

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

GET https://sslmate.com/api/v3/orders/example.com/certs Authorization: Bearer 123_Noo5ohpuK6seed5taeku

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