Documentation REST API

Getting Started

ZeroSSL makes it easy to create, install and manage SSL certificates of any kind by offering an easy-to-use user interface with clear instructions and plenty of automation in the background. To better serve customers who are looking to put SSL management on autopilot completely, we are offering a full-fledged SSL REST API that will allow you to automate all the actions our UI supports and perform them using a secure, fast and straightforward API interface.

Base URL

API requests are made using a simple API base URL, variable endpoints and requests using HTTPS GET and POST. No matter which API endpoint you are using, the value below will be your base URL:

api.zerossl.com

HTTPS redirection

The ZeroSSL API redirects HTTP to HTTPS for security reasons. We recommend using HTTPS directly for your requests to avoid any redirection issues.

Access Key

Each user account is assigned a unique API access key, which must be included in your API requests. You can find your API access key in the Developer section of your ZeroSSL management console.

Authentication with Access Key via Header (Recommended)

Send an Authorization Header containing your Access Key.

Syntax:

Authorization: ApiKey aaaaaaaaaaaaaaaaaaaaaaaaaaaaa1

Example using curl:

curl --header "Authorization: ApiKey aaaaaaaaaaaaaaaaaaaaaaaaaaaaa1" api.zerossl.com

Recommended Approach

For better security, this is the recommended approach. We also strongly advise renewing your access key regularly.

DEPRECATED: Authorization via GET Parameter

For legacy purposes, we still support passing the access key as a GET parameter. Please do not use this method for new implementations. This section remains in the documentation temporarily to allow developers time to update existing integrations.

api.zerossl.com/example_endpoint?access_key=EXAMPLE_KEY

Deprecation Warning

This approach is deprecated. It will be permanently removed in the future following an official announcement and a transition period.

Methods

The ZeroSSL API currently supports around 10 methods you can use to create, verify, download and cancel existing or new SSL certificates. Some methods are making use of HTTPS GET parameters, others require HTTPS POST parameters to work.

To get started right away, please find a list of available API methods below:

Alternative: Send JSON requests

Instead of using HTTP GET or POST parameters, you can submit JSON in every API request. The parameters are exactly the same as described in the API documentation, the JSON has to be in the request body.

Allowed request content

In certain endpoints we require you to send lists as comma-separated strings. Currently, this also applies to JSON requests, you can not send arrays instead (yet).

Header required

If you are submitting a JSON request it is mandatory to set the Content-Type: application/json header.

JSON request body sample for Create Certificate:

{
    "certificate_domains": "zerossl.dev",
    "certificate_validity_days": 90,
    "certificate_csr": "CSR",
    "strict_domains": 1
}

API integrator information

Read this section carefully if you are going to automate processes using our API for instance by writing your own scripts (Sample API integration).

API changes

Sometimes new functionality is added to the ZeroSSL API, and in rare cases the functionality of endpoints may change a little. The ZeroSSL API basically follows the rules of the tolerant reader pattern. If you implement the ZeroSSL API in your web application your web application should be tolerant in the following regards:

Added attributes: Additional attributes might be added to existing JSON objects
Endpoints: New endpoints might be published over time
Enumerations: Additional options might be added over time
Response codes: The HTTP response codes in case of API errors (4xx or 5xx) might change in rare cases (in case of success the response code is always HTTP 200)
Typing: In very rare cases we might change the returned type within a JSON response (e.g. integer instead of string). Please typecast on your side just to be sure nothing breaks.

In general the current API is treated as conservative as possible, and we try to do as few changes as possible. Endpoints as well as attributes shall never be removed. Anyway try to be tolerant in your implementations.

Proper use of the API

The ZeroSSL API is protected against misuse. Write appropriate integrations which use the ZeroSSL API in a reasonable way. In case of heavy misuse — which endangers our systems' functionality and therefore other users — you might get blocked (temporarily or even permanently).

Create Certificate →