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

Introduction

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 cannot 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?page=3>; rel="next"

Orders

An order specifies what you need in a certificate: the identifiers (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 identifiers. 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 60 days 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 the 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 identifier, but by convention it is usually the same as the order's first identifier.

If this field is omitted, the first identifier is used. The order name cannot be changed after an order has been created.

Read-only
identifiers array

Information about the identifiers (example.com, www.example.com, *.example.com, etc.) that you need in your certificate. Every identifier that you wish to secure with your certificate must be listed here. The identifiers will be placed in the certificate's subject alternative name (SAN) extension. The first identifier will be placed in the certificate's common name field. This field must always have at least one entry.

Adding or removing an identifier automatically resets the order's csr field to null. If the order is unmanaged, you must provide a new CSR containing the new set of identifiers. (If the order is managed, sslmate-agent will provide the CSR for you.) SSLMate will not issue a new certificate until an updated CSR is provided.

Every identifier must be approved by an authorized party before a certificate can be issued for it. It is possible to automate this process so that approval is instantaneous and automatic.

Adding identifiers to an existing order may cause your account to be billed if the product type is priced by number of identifiers.

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 60 days before the current certificate expires. When false, SSLMate only issues a new certificate when you explicitly change the order's CSR, identifiers, or product. 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, although this can be changed in your account settings. Auto-renewal is highly recommended.

product stringStill under development. Do not include this field when creating an order.
renewal_product string or nullStill 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 identifier, and the CSR's subject alternative name (SAN) extension must contain all the order's identifiers (including the first). See the CSR Requirements section for details.

revision integer

A 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 (because the current one is expiring soon, or you've changed the order's identifiers), 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.)

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", "identifiers": [ { "type": "dns", "value": "example.com", "approval": "http" }, { "type": "dns", "value": "www.example.com", "approval": "http" } ], "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 at least the identifiers field. 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 { "identifiers": [ { "type": "dns", "value": "example.com", "approval": "http" }, { "type": "dns", "value": "www.example.com", "approval": "http" } ], "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 Identifiers)

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

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

The identifier object

The identifier object represents a name, such as a DNS name, for which a certificate is valid. The identifiers for an order are found in the order object's identifiers field, which is an array of identifier objects.

Attributes
type stringType of identifier. Use "dns" for a DNS name.
value stringFor "dns" identifiers: a fully-qualified domain name, optionally prefixed with "*." for a wildcard. Examples: example.com, www.example.com, *.example.com
approval stringHow this identifier will be approved. May be "http", "dns", or an authorized administrative email address. See the approval documentation for details.

Example identifier

{ "type": "dns", "value": "www.example.com", "approval": "http" }

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 account page to configure your webhook URL.

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 identifier in order object. Exactly one CN attribute must be present.

  • The subject alternative name extension must contain the exact same identifiers 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 identifiers 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. SSLMate requests new certificates when you modify the order's CSR Pending certificate objects are created automatically by SSLMate when you create and modify orders and keys, and 60 days before a current certificate expires. When the certificate is issued, SSLMate updates the certificate object, populating the leaf field and setting the state to valid. Once a certificate is issued, its leaf field and expiration date are immutable; renewed certificates are placed in a new certificate object.

Certificate objects can be accessed directly by their URL, but it's more convenient to access certificates by expanding the order's current_cert field, which always contains the order's best certificate.

The certificate object

Attributes
id integerThe 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.

identifiers array

The identifiers (DNS names) present in this certificate. The first identifier is in the certificate's common name field. All identifiers (including the first) are in the certificate's subject alternative name (SAN) extension. The approval field is not present in the identifier object.

Read-only
expiration stringThe date and time, in RFC3339 format, when this certificate expires. Read-only
not_before stringThe date and time, in RFC3339 format, when this certificate became valid. This time is always in the past. Read-only
sha256 stringThe SHA-256 fingerprint of the DER-encoded leaf certificate, as lowercase hex. Read-only
key_type stringThe type ("rsa" or "ecdsa") of key certified by this certificate. Read-only
cluster string or nullThe name of the sslmate-agent cluster which created the key certified by this certificate. Null if it was created manually. Read-only
leaf stringThe DER-encoded leaf certificate, transmitted in base64 with no line breaks. Read-only
chain arrayAn 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 stringThe 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

{ "id": 19334, "state": "valid", "identifiers: [ { "type": "dns", "value": "example.com" }, { "type": "dns", "value": "www.example.com" } ], "not_before": "2017-07-25T19:14:00-00:00", "not_after": "2017-10-23T19:14:00-00:00", "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