Introduction

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!

API Endpoint

https://sslmate.com/api/v2

Authentication

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.

In general, authenticating with your API key is equivalent to authenticating with your username and password, unless a purchase exceeds your account's daily purchase limit (if set). In that case, you must authenticate with your username and password to override the purchase limit.

Example Request

curl https://sslmate.com/api/v2/certs/example.com \ -u 123_sampleapikey:

Sandbox

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.

Sandbox API Endpoint

https://sandbox.sslmate.com/api/v2

Errors

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:

Attributes
reason string A short machine-readable code that describes the error. The code for a particular error is guaranteed not to change.
message string A human-readable message. The value of this attribute is only suitable for human consumption; the exact wording of messages may change without notice. For a machine-readable code, use the reason attribute.
param string The name of the request parameter that was invalid. Only present if the error is parameter-specific.
retry_after integer Number of seconds after which to retry the request. If this attribute is present, the client should only retry the request after this many seconds have elapsed.

Example Error

{ "reason": "bad_bitsize", "message": "RSA keys must be 2048, 3072, or 4096 bits", "param": "csr" }

Expanding objects

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.

Example Request

curl https://sslmate.com/api/v2/certs/example.com?expand=current.crt \ -u 123_sampleapikey:

Certificates and Certificate Instances

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.

It is also possible to create a certificate instance by importing an X509 certificate purchased outside of SSLMate.

Certificates

The certificate object

Attributes
exists booleanWhether a certificate with this common name exists in your account.
cn stringThe common name.
wildcard boolean
dn objectJSON object describing the distinguished name (DN) of this certificate, to be used when generating a CSR. Each element of the hash corresponds to different attribute of the DN.
auto_renew boolean If true, the certificate will be automatically renewed 60 days prior to expiration. Note: automatic renewal requires you to use HTTP or DNS approval, and to integrate your HTTP server or DNS provider with SSLMate, as described in the approval documentation.
muted booleanIf true, expiration reminders are not sent.
approval_method string or nullHow domain control is verified: "email", "http", or "dns". null if and only if exists is false.
approver_email stringThe email address to which domain validation emails should be sent. This attribute is present if and only if approval_method is "email".
http_approval objectAn approval object with HTTP options describing how to approve this certificate over HTTP. This attribute is present if and only if approval_method is "http".
dns_approval objectAn approval object with DNS options describing how to approve this certificate over DNS. This attribute is present if and only if approval_method is "dns".
type string or nullThe type of the certificate: "dv" or "ev". Changing this attribute only affects future renewals and purchases. The current active instance does not change type. null if and only if exists is false.
sans array or nullAn array of SAN (subject alternative name) objects representing the subject alternative names of this certificate. Non-null if and only if this is a multi-hostname certificate.
tags arrayAn array of strings representing user-defined tags for this certificate object.
csr stringPEM-encoded CSR in PKCS#10 format. Guaranteed to have a trailing newline character. Only present if expanded.
pubkey_hash string or nullThe SHA-256 hash of the CSR's DER-encoded public key, encoded in lowercase hex. null if and only if exists is false.
current objectThe current active certificate instance for this certificate, if one exists. Only present if expanded.
pending objectThe current pending certificate instance for this certificate, if one exists. Only present if expanded.

Example certificate

{ "exists": true, "cn": "www.example.com", "wildcard": false, "dn": { "C": "US", "ST": "CA", "L": "Berkeley", "O": "SSLMate", "CN": "www.example.com" }, "auto_renew": true, "muted": false, "approval_method": "email", "approver_email": "webmaster@example.com", "type": "dv", "sans": null, "tags": ["alice", "bob"], "pubkey_hash": "70e7aa036fb4dc2c8d8f...98ce6cae7048f2f54d48" }

Create/update a certificate

Given a common name, create or update the certificate object for that common name.

If a certificate with this common name already exists in your account, then all arguments are optional in the request. Only the certificate attributes specified in the request are updated; all others keep their current values.

If no certificate with this common name exists in your account, one will be created, in which case all the arguments marked "required for new certs" must be specified.

Arguments
csrPEM-encoded CSR in PKCS#10 format. Required for new certs. See the Generating CSRs section for more information about CSRs.
approval_method"email", "http", or "dns". Required for new certs.
approver_emailEmail address for email approval. Required for new certs if approval_method is "email".
typeType of certificate. Defaults to "dv" for new certs.
auto_renew
muted
tags.TAGNAME Add (by specifying a value of 1) or remove (by specifying a value of 0) the user-defined tag named TAGNAME.
Returns

Returns a certificate object if the request was valid, and returns an error otherwise.

Definition

POST https://sslmate.com/api/v2/certs/COMMON_NAME

Example Request

curl https://sslmate.com/api/v2/certs/example.com \ -u 123_sampleapikey: \ --data-urlencode csr=$'-----BEGIN CERTIFICATE REQUEST-----...' \ -d approval_method=email \ -d approver_email=webmaster@example.com \ -d tags.tagtoadd=1 \ -d tags.tagtoremove=0

Example Response

See certificate object.

Buy a certificate

Purchase and issue a certificate instance for the certificate object with the given common name. A new certificate instance will be created using the type, approval_method, approver_email, and csr of the certificate object. Therefore, you must have already created or updated the certificate object with the desired parameters. Your account will be charged for the purchase, and the expiration date of the new certificate instance will be one year from today's date.

Arguments
invoice_noteA custom note to be included with the invoice for this purchase.
email_invoice_toEmail address to which a copy of the invoice should be sent.
Returns

Returns the newly-created certificate instance object if the purchase succeeds, and returns an error otherwise.

The certificate instance will be in the pending state until it is approved. You should poll for the certificate instance until it becomes active, as described under Retrieve a certificate instance.

Definition

POST https://sslmate.com/api/v2/certs/COMMON_NAME/buy

Example Request

curl https://sslmate.com/api/v2/certs/example.com/buy \ -u 123_sampleapikey: \ -X POST

Example Response

See certificate instance object.

Reissue a certificate

Reissue a certificate instance for the certificate object with the given common name. A new certificate instance will be created using the type, approval_method, approver_email, and csr of the certificate object. Unlike buying a new certificate, reissuing does not cost money, and the new certificate instance will have the same expiration date as the certificate's current active instance. An active, non-expired certificate instance must exist for this certificate.

Reissuing a certificate is useful for rekeying after a key has been lost or compromised. To rekey, you should first update the certificate object with a new CSR for the new key, and then make a reissue request.

Returns

Returns the newly-created certificate instance object if the reissue succeeds, and returns an error otherwise.

The certificate instance will be in a pending state until it is approved. You should poll for the certificate instance until it becomes active, as described under Retrieve a certificate instance.

Definition

POST https://sslmate.com/api/v2/certs/COMMON_NAME/reissue

Example Request

curl https://sslmate.com/api/v2/certs/example.com/reissue \ -u 123_sampleapikey: \ -X POST

Example Response

See certificate instance object.

Redo certificate approval

Redo certificate approval for the given certificate's pending instance, using the approval settings from the certificate object. If using email approval, the email will be (re-)sent. If using HTTP approval, the file will be (re-)fetched. If using DNS approval, the DNS record will be (re-)checked.

This request can be used if you have changed a certificate's approval details while an instance was pending and you would like to use the new details to approve the pending instance, or if the first attempt at approval failed and you need to try again.

The certificate must have a pending instance for this request to succeed.

Returns

Returns the certificate's pending certificate instance object if the action succeeds, and returns an error otherwise.

Definition

POST https://sslmate.com/api/v2/certs/COMMON_NAME/redo_approval

Example Request

curl https://sslmate.com/api/v2/certs/example.com/redo_approval \ -u 123_sampleapikey: \ -X POST

Example Response

See certificate instance object.

Revoke a certificate

Revoke one or more certificate instances for the certificate object with the given common name. By default, all certificate instances except for the active one are revoked. If the all argument is true, even the active instance is revoked. See the general documentation on revoking for more information.

Arguments
all If "true", all certificate instances are revoked, even the active instance. See the documentation on revoking for a warning about revoking all instances.
Returns

Returns the following object if the revoke succeeded, and returns an error otherwise.

Attributes
status string"pending" if the revocation is pending, or "revoked" if the revocation has completed.
num_revoked integerThe number of instances that have been revoked.
num_active integerThe number of instances that are still active.
num_imported integerThe number of instances that could not be revoked because they were imported.

Definition

POST https://sslmate.com/api/v2/certs/COMMON_NAME/revoke

Example Request

curl https://sslmate.com/api/v2/certs/example.com/revoke \ -u 123_sampleapikey: \ -X POST

Example Response

{ "status": "pending", "num_revoked": 3, "num_active": 1, "num_imported": 0, }

Test a certificate

Test the installation of the given certificate by conducting a TLS handshake with one or more hosts (by default, the common name of the certificate is used as the hostname) and checking that the active certificate instance is served correctly.

Arguments
hostname The hostname or IP address to test. Argument be specified more than once to test multiple hosts. Defaults to all valid hostnames of the certificate (common name plus subjectAltNames).
port The port number to test. Defaults to 443 (HTTPS).
Returns

Returns the following object if you have an active certificate in your account with this common name, and returns an error otherwise.

Attributes
result arrayAn array of test result objects, one per host tested. If a hostname resolves to multiple IPv4 or IPv6 addresses, they will all be tested and returned in separate test results.
The test result object
Attributes
hostname stringThe hostname to which this result applies.
ip_address stringThe IPv4 or IPv6 address to which this result applies.
status stringOne of: "conclusive" (the test produced a conclusive result), "connect_error" (could not connect to this host), "handshake_error" (TLS handshake failed), or "internal_error".
correct boolTrue if and only if the correct certificate was served. This attribute is present if and only if status is "conclusive".
chained boolTrue if and only if the correct certificate chain was served. This attribute is present if and only if status is "conclusive".
dummy boolTrue if and only if the the certificate was a temporary certificate. This attribute is present if and only if status is "conclusive".
error stringA human-readable error message. This attribute is present if and only if status is not "conclusive".

Definition

GET https://sslmate.com/api/v2/certs/COMMON_NAME/test

Example Request

curl https://sslmate.com/api/v2/certs/example.com/test \ -u 123_sampleapikey:

Example Response

{ "result": [ { "hostname": "example.com", "ip_address": "198.51.100.125", "status": "conclusive", "correct": true, "chained": true, "dummy": false }, { "hostname": "example.com", "ip_address": "2001:db8:c40:8a::1", "status": "conclusive", "correct": true, "chained": true, "dummy": false } ] }

Retrieve a certificate

Given a common name, return the certificate object for that common name. If no certificate with this common name exists in your account, the exists attribute in the returned object will be false.

Returns

Returns a certificate object if a valid common name was provided, and returns an error otherwise.

Definition

GET https://sslmate.com/api/v2/certs/COMMON_NAME

Example Request

curl https://sslmate.com/api/v2/certs/example.com \ -u 123_sampleapikey:

Example Response

See certificate object.

Certificate instances

The certificate instance object

Attributes
id integerUnique ID.
state stringpending, active, expired, revoked, or canceled.
expiring booleanThis certificate is active but expiring imminently.
source stringEither "sslmate" (purchased from SSLMate) or "import" (imported to SSLMate).
type string or nullThe type of this certificate (e.g. "dv"). May be null only if this certificate is imported.
sans array or nullAn array of SAN (subject alternative name) objects representing the subject alternative names of this certificate instance. Non-null if and only if this is a multi-hostname certificate.
pubkey_hash stringThe SHA-256 hash of this certificate's DER-encoded public key, encoded in lowercase hex.
sha1_fingerprint string or nullThe SHA-1 hash (in lowercase hex) of the DER-encoded certificate.
sha256_fingerprint string or nullThe SHA-256 hash (in lowercase hex) of the DER-encoded certificate.
expiration timestamp or nullThe expiration time of this certificate, as a UNIX timestamp (number of seconds since January 1, 1970).
csr stringPEM-encoded CSR in PKCS#10 format. Guaranteed to have a trailing newline character. Only present if expanded.
crt stringPEM-encoded X509 certificate. Guaranteed to have a trailing newline character. Only present if expanded.
chain arrayAn array of zero or more PEM-encoded X509 certificates that form the intermediate certificate chain for this certificate. The first certificate in the chain issued this certificate, and the last certificate in the chain was issued by a root certificate. The root certificate itself is not included. Each certificate is terminated with a newline character. Only present if expanded.
root stringThe PEM-encoded X509 root certificate (the issuer of the last certificate in the chain, or of this certificate if the chain is empty). Guaranteed to have a trailing newline character. Only present if expanded.
invoice_id string or nullInvoice ID for the purchase of this certificate. Null for imported certs.
approval_method string or nullHow domain control was verified. Null for imported certs.
approver_email stringThe email address used to approve the certificate. Applicable if and only if approval_method is "email".
approval_email_from stringThe email address from which the approval email was sent. Applicable if and only if approval_method is "email".

Example certificate instance

{ "id": 331, "state": "active", "expiring": false, "source": "sslmate", "type": "dv", "pubkey_hash": "70e7aa036fb4dc2c8d8f...98ce6cae7048f2f54d48", "sha1_fingerprint": "75d46dc4e46045617b65897b6870042565d95512", "sha256_fingerprint": "923ed7d285fbf9086ced...d02b16fd4bade8266d70", "expiration": 1427442542, "invoice_id": 1001, "approval_method": "email", "approver_email": "webmaster@example.com", "approval_email_from": "sslorders@geotrust.com" }

Import a certificate instance

Create a certificate instance using an X509 certificate that was not purchased through SSLMate. The X509 certificate that you upload must have the same common name as the certificate object, and must have the same public key as the certificate object's CSR. Therefore, you must have already created or updated the certificate object with the appropriate CSR.

SSLMate will automatically construct the optimal certificate chain for the imported certificate and store it in the certificate instance's chain attribute. You can only import certificates that are signed by a public certificate authority and are not expired.

Arguments
crt The PEM-encoded X509 certificate to import. Required.
Returns

Returns the newly-created certificate instance object if the import was successful, and returns an error otherwise.

The certificate instance will be in the active state.

Definition

POST https://sslmate.com/api/v2/certs/COMMON_NAME/instances

Example Request

curl https://sslmate.com/api/v2/certs/example.com/instances \ -u 123_sampleapikey: \ --data-urlencode crt=$'-----BEGIN CERTIFICATE-----...'

Example Response

See certificate instance object.

Retrieve a certificate instance

Retrieve a certificate instance object for the certificate object with the given common name. Instances can be retrieved either by their unique instance ID, or by the value of their pubkey_hash attribute. If a certificate has more than one instance with the requested pubkey_hash, then the most recent active instance is returned.

Arguments
poll If this argument is specified, and the certificate instance is pending, the server will wait until the certificate instance is no longer pending before returning a result. The server will wait at most the number of seconds specified by the poll argument, but may return sooner even if the certificate instance is still pending. The client should be prepared to retry the request.
Returns

Returns a certificate instance object if the requested certificate instance exists, and returns an error otherwise. If the poll argument was specified, and the certificate instance is still pending, a 412 Precondition Failed error is returned. The error object's retry_after attribute will be set, and the client must not retry the request until after this many seconds have elapsed.

Definition

GET https://sslmate.com/api/v2/certs/COMMON_NAME/instances/INSTANCE_ID
GET https://sslmate.com/api/v2/certs/COMMON_NAME/instances/pubkey_hash:HASH

Example Request

curl https://sslmate.com/api/v2/certs/example.com/instances/512 \ -u 123_sampleapikey:

Example Response

See certificate instance object.

Approval Objects

An approval object describes how a certificate can be approved with HTTP or DNS. HTTP approval works by serving a plain text file with specific contents at a specific location on a specific HTTP host. DNS approval works by publishing a DNS record of a specific type with a specific name and value.

If you have integrated your web server or DNS provider with SSLMate then you can ignore the approval objects returned by the API. Simply specify "http" or "dns" approval when creating the certificate object, and SSLMate will care of provisioning the HTTP file or DNS record.

The approval object specifies these values. Since there may be more than one usable set of values (e.g. a certificate for www.example.com can be approved by hosting a file at either www.example.com or example.com), the values are specified in an array of option objects. You can choose whichever option is most convenient.

Approval objects are found in the http_approval and dns_approval attributes of certificate objects.

Attributes
options arrayAn array of approval option objects (either HTTP or DNS, depending on context) that can be used to approve the certificate.

Example HTTP approval info object

{ "options": [ { "hostname": "www.example.com", "path": "/8F349882D442DBAE4FA4E487F6C312F2.txt", "value": "ac60fbadd9dc6f5ce549f07984b1864af8d308ca\ncomodoca.com\n" }, { "hostname": "example.com", "path": "/8F349882D442DBAE4FA4E487F6C312F2.txt", "value": "ac60fbadd9dc6f5ce549f07984b1864af8d308ca\ncomodoca.com\n" }, ] }

The HTTP approval option object

Describes the file which you must serve from your server to approve the certificate. The file must contain the given contents and be served at the given path on the given host. The file must be available over HTTP or HTTPS, and cannot be a redirect to a different URL.

Attributes
hostname stringThe hostname from which the file must be served.
path stringThe path from which the file must be served.
content stringThe exact content of the file that must be served. No trailing whitespace is allowed.

Example HTTP approval option

{ "hostname": "example.com", "path": "/8F349882D442DBAE4FA4E487F6C312F2.txt", "value": "ac60fbadd9dc6f5ce549f07984b1864af8d308ca\ncomodoca.com\n" }

The DNS approval option object

Describes the DNS record which you must publish to approve the certificate. The record must be of the given type, have the given name, and resolve to the given value.

Attributes
name stringThe fully-qualified name of the DNS record that must be published.
type stringThe type of the DNS record (e.g. CNAME) that must be published.
value stringThe value of the DNS record that must be published. For TXT records, the value will contain the necessary quote characters; do not add your own.

Example DNS approval option

{ "name": "8f349882d442dbae4fa4e487f6c312f2.example.com", "type": "CNAME", "value": "ac60fbadd9dc6f5ce549f07984b1864af8d308ca.comodoca.com." }

Subject Alternative Names (SANs)

A SAN object describes the subject alternative name of a multi-hostname certificate, such as the SAN's type, name, and approval details.

SAN objects are found in the sans array attribute of certificate and certificate instance objects. The sans attribute is non-null if and only if the certificate is a multi-hostname certificate.

The SAN object

Attributes
type stringThe type of name. Currently only "dns" is supported.
value stringThe name itself. In the case of "dns" SANs, this is the hostname.
approval_method stringHow control over the name is verified: "email", "http", or "dns".
approver_email stringThe email address to which domain validation emails should be sent. This attribute is present if and only if approval_method is "email".
http_approval objectAn approval object with HTTP options describing how to approve this certificate over HTTP. This attribute is present if and only if approval_method is "http".
dns_approval objectAn approval object with DNS options describing how to approve this certificate over DNS. This attribute is present if and only if approval_method is "dns".

Example SAN

{ "type": "dns", "value": "subdomain.example.com", "approval_method": "email", "approver_email": "webmaster@example.com" }

Create/update a SAN

Given the common name of a certificate object, a SAN type (e.g. "dns"), and the SAN value (i.e. the hostname), create or update a SAN object under the certificate object.

If a SAN of the given type and value already exists in the given certificate object, then all request arguments are optional, and only the attributes specified in the request are updated; all others keep their current values.

If no SAN with the type and value exists under the certificate object, a new SAN object is created, in which case all the arguments marked "required for new SANs" must be specified.

If the certificate object is not currently multi-hostname (i.e. its sans attribute is null), it will be converted. However, it is not possible to reissue a certificate object that was previously a standard certificate as a multi-hostname certificate. Instead, you must buy a new certificate.

Arguments
approval_method"email", "http", or "dns". Required for new SANs.
approver_emailEmail address for email approval. Required for new SANs if approval_method is "email".
Returns

Returns a SAN object if the request was successful, and returns an error otherwise.

Definition

POST https://sslmate.com/api/v2/certs/COMMON_NAME/sans/SAN_TYPE/SAN_VALUE

Example Request

curl https://sslmate.com/api/v2/certs/example.com/sans/dns/san.example.com \ -u 123_sampleapikey: \ -d approval_method=email \ -d approver_email=webmaster@example.com

Example Response

See SAN object.

Delete a SAN

Given the common name of a certificate object, a SAN type (e.g. "dns"), and the SAN value (i.e. the hostname), delete the corresponding SAN object under the certificate object.

Note that removing all SANs individually does not convert the certificate object to a standard certificate. Instead, it is left as a multi-hostname certificate with zero configured SANs. To convert the certificate to a standard certificate, see delete all SANs below.

Returns

Returns an empty body with a status code of 204 ("No Content") if the request was successful, and returns an error otherwise.

Definition

DELETE https://sslmate.com/api/v2/certs/COMMON_NAME/sans/SAN_TYPE/SAN_VALUE

Example Request

curl https://sslmate.com/api/v2/certs/example.com/sans/dns/san.example.com \ -u 123_sampleapikey: \ -X DELETE

Example Response

This request does not return a response.

Delete all SANs

Given the common name of a certificate object, delete all of its SAN objects and convert it to a standard certificate. The certificate object's sans attribute will be null after this operation.

Note that it is not possible to reissue a certificate object that was previously a multi-hostname certificate as a standard certificate. Instead, the change will take effect on the next purchase.

Returns

Returns an empty body with a status code of 204 ("No Content") if the request was successful, and returns an error otherwise.

Definition

DELETE https://sslmate.com/api/v2/certs/COMMON_NAME/sans

Example Request

curl https://sslmate.com/api/v2/certs/example.com/sans \ -u 123_sampleapikey: \ -X DELETE

Example Response

This request does not return a response.

Webhook

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

Visit your account page to set your webhook URL.

Generating CSRs

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:

$ openssl req -new -newkey rsa:2048 -nodes -subj /C=US/CN=COMMON_NAME -keyout KEYFILE

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:

$ sslmate req --key-file=KEYFILE --csr-file=CSRFILE COMMON_NAME

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.

Cookbook of Common Operations

Buying a certificate
  1. Generate a key and CSR.
  2. Create a certificate object with the CSR generated in step 1, and the desired approval method.
  3. If using HTTP or DNS approval, install the HTTP file or publish the DNS record as described by the http_approval or dns_approval attributes of the certificate object returned in step 2. See the section on approval objects for details.
  4. Buy the certificate. Make note of the id attribute of the returned certificate instance object.
  5. If using email approval, you must now respond to the email sent to the address specified in the approver_email attribute of the certificate object.
  6. Retrieve the certificate instance with the ID of the certificate instance object returned in step 4, repeating as necessary until the certificate instance's state becomes active. (This typically takes 30-60 seconds. You can use the poll argument to long-poll.) When retrieving the certificate instance, ask for the crt and chain attributes to be expanded. Once the instance is active, you will find the X509 certificate in the crt attribute, and the chain certificate(s) in the chain attribute.
Renewing a certificate

If a certificate's auto_renew attribute is false, then complete steps 3 through 6 of "Buying a certificate" above. There is no need to generate a new CSR or update the existing certificate object.

If a certificate's auto_renew attribute is true and you have integrated your HTTP server or DNS provider with SSLMate as described in the approval documentation, then SSLMate will automatically purchase a new certificate for you 60 days before the current certificate expires. Once issued, the new certificate instance will be available under the current attribute of the certificate object. You can also receive the new certificate via a webhook.

Rekeying a certificate
  1. Generate a new key and CSR.
  2. Update the certificate object with the CSR generated in step 1.
  3. If using HTTP or DNS approval, install the HTTP file or publish the DNS record as described by the http_approval or dns_approval attributes of the certificate object returned in step 2. See the section on approval objects for details. You can remove any HTTP files or DNS records previously created for this certificate.
  4. Reissue the certificate. Make note of the id attribute of the returned certificate instance object.
  5. Complete steps 5 through 6 of "Buying a certificate" above.