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

The SSLMate API is centered around REST principles. Requests are made to predictable, resource-oriented URLs using standard HTTP verbs and HTTP authentication. Request arguments are encoded as key/value pairs in standard HTTP form encoding (application/x-www-form-urlencoded), and are passed in either the query string (for GET requests) or in the request body (for POST requests). All responses, including errors, are JSON. Requests and responses use the UTF-8 character encoding.

SSLMate will only make backwards-compatible changes to this API endpoint (e.g. adding new requests, adding new attributes to responses, adding new optional arguments to requests). Backwards-incompatible changes will be avoided if at all possible, but should such a change become necessary, SSLMate will create a new API endpoint with a higher version number, and preserve the old API endpoint for at least 12 months following the introduction of the new endpoint.

You may want to consult the cookbook of common operations for guidance on how to purchase, renew, and reissue a certificate.

Feel free to get in touch if you have any questions or need help using the API. SSLMate is happy to help!

You authenticate to the SSLMate API by providing either your username and password, or your API key, which can be found on your account page. Your API key has almost complete access to your account, so you should keep it secret.

Authentication uses HTTP Basic Auth. When authenticating with your API key, provide the key as the basic auth username and leave the password empty.

Authenticating with your API key is equivalent to authenticating with your username and password.

To facilitate testing, SSLMate operates a sandbox website at https://sandbox.sslmate.com, with its own API endpoint (shown to the right). Purchases made on the sandbox website are free and certificates 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.

SSLMate uses standard 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.

The following JSON object is returned by the server for any unsuccessful request:

Some objects contain attributes marked "expandable." These attributes are not included in responses by default, but can be included by passing the name of the attribute 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 attributes of nested objects using the dot character. For example, expanding current.crt on a certificate object will expand the current attribute into a full certificate instance, and then expand the crt attribute of that certificate instance into a full certificate string.

You can expand multiple attributes by specifying the expand parameter multiple times. Note that the expand parameter is always passed in the query string, even for POST requests.

The SSLMate API is centered around two types of objects: certificates and certificate instances.

Certificate objects specify the desired properties (e.g. CSR, approval method) for a particular host's certificate. Certificate instances represent a specific instantiation of a certificate and are created when a certificate is bought or reissued. There is a one-to-many relationship between certificates and certificate instances. For example, the certificate for www.example.com might contain three instances: one instance that was created when the cert was bought on March 10, 2014, a second instance that was created when the cert was reissued on April 8, 2014, and a third instance that was created when the cert was bought again (for renewal) on March 10, 2015.

Certificate instances are created when you buy or reissue a certificate object. The new certificate instance will use the details (CSR, approval method, etc.) of the certificate object at the time of the purchase/reissue. To purchase a brand-new certificate, you would first create a certificate object with the desired CSR and approval details, and then buy the certificate. The signed X509 certificate will be stored in the newly-created certificate instance (once approved).

Certificate instances are immutable. To reissue a certificate with a new key, you would not modify a particular instance, but rather update the CSR of the certificate object, and then reissue that certificate object, creating a new certificate instance corresponding to the new CSR/key. Changing the attributes of a certificate object does not affect any existing instances.

If a certificate's sans attribute is null, SSLMate adds an automatic SAN using the below logic:

• If the common name starts with www., SSLMate adds a SAN that is formed by removing the www. prefix.
• If the common name starts with *., SSLMate adds a SAN that is formed by removing the *. prefix.
• Otherwise, SSLMate adds a SAN that is formed by prefixing www. to the common name.

The automatically-added SAN uses the same approval method as the common name.

If you don't want your certificate to have the automatically-added SAN, set the sans attribute to the empty array.

You can configure SSLMate to POST a certificate object, with current.crt and current.chain expanded, when a certificate is issued.

Visit your webhooks page to add a webhook endpoint.

The SSLMate API accepts and returns CSRs in PEM-encoded PKCS#10 format. CSRs must correspond to an RSA key of 2048, 3072, or 4096 bits, or to an ECDSA key on the NIST P-256 (secp256r1 / prime256v1) or NIST P-384 (secp384r1) curves. The CSR's distinguished name must contain the certificate's common name in the CN attribute, and a valid two-letter ISO country code (e.g. US) in the C attribute.

To programmatically generate a private key and a corresponding CSR for use with a certificate object, the following openssl command can be used:

Replace COMMON_NAME with the certificate object's common name. The CSR will be written to standard out, which you should upload to SSLMate when creating or updating the certificate object. The private key will be saved to a file named KEYFILE.

You can also generate a private key and CSR using the sslmate req command (from the SSLMate client) as follows:

The private key and CSR will be written to KEYFILE and CSRFILE, respectively. Either or both filenames may be - to write to standard out.

sslmate req is a standalone command that works without contacting SSLMate servers.