Skip to content

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

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

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

{ "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

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

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 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.

Expandable
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 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, "muted": false, "paused": false, "product": "sectigo", "key_type": "rsa", "revision": 1024, "current_cert_download": "https://certs.sslmate.com/tZwf1MOnfY8AVdXUeHhM/example.com.rsa.pem", "pubkey_sha256": "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de" }

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

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.

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)

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

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).

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:

  • 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'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. 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", "current": true, "dns_names: ["example.com", "www.example.com"], "not_before": "2017-07-25T19:14:00Z", "expiration": "2017-10-23T19:14:00Z", "sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", "key_type": "rsa", "pubkey_sha256": "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de", "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:

openssl base64 -A -d | openssl x509 -inform DER