# LeaderSSL Partner API Reference

[TOC]

## General information

### Base URL

All calls go to https://api.leaderssl.com over HTTPS. Requests over plain HTTP are redirected with HTTP code 301, which turns a POST into a GET in most clients, so always use https.

### Authentication

Sign in once ([1. Authentication](#1-authentication)) and send the returned token with every other call in the X-AUTH-TOKEN HTTP header. The token can also be sent as the auth_token query parameter; this form is deprecated because the token then appears in request logs.

A token has no fixed lifetime. A new signin returns the same token when the account record changed less than 12 hours ago; otherwise it issues a new token and the previous token stops working. Store the token and sign in again only when a call answers HTTP code 401.

### Responses and errors

All responses are JSON-encoded in UTF-8 unless a section says otherwise. IDs are integers.

* HTTP code 401 - the token is missing or not valid: {"error":"Undefined X-AUTH-TOKEN or auth_token"} or {"error":"Invalid X-AUTH-TOKEN or auth_token"}. Sign in again.
* HTTP code 403 - your login may not perform the action: {"error":"You do not have permission for this action"}. Logins with a restricted role (for example a billing-only login) cannot order or change certificates.
* HTTP code 404 - the certificate ID does not exist or belongs to another account. Most calls answer with a body that is not meant to be parsed; [4. Certificate status](#4-certificate-status), [14. Certificate details](#14-certificate-details) and [15. Download certificate bundle](#15-download-certificate-bundle) answer with JSON (see their Errors).
* HTTP code 422 - the request was understood but cannot be processed. The body is {"errors":[...]} for a new order, {"errors":"..."} for a download, or {"success":false,"error":"..."} for a reissue and for the DCV status.
* Some calls answer HTTP code 200 with {"success":false,"result":"..."} when the action was refused (change DCV, resend DCV, cancel). Always check the success field.

Cross-origin requests are allowed from any origin (Access-Control-Allow-Origin: *) for the methods GET, POST and OPTIONS.

### Machine-readable versions

* This reference as Markdown: https://api.leaderssl.com/doc.md
* OpenAPI 3.1 description of the calls: https://api.leaderssl.com/openapi.json
* Index for AI tools (llms.txt): https://api.leaderssl.com/llms.txt

## 1. Authentication

### Endpoint

https://api.leaderssl.com/api/v1/users/signin

### Method

POST

### Parameters

* login. Your account login (email address)
* password. Your account password

Both can be sent as form fields or as a JSON object.

### Return

HTTP code 200, a JSON-encoded object with the credentials. It contains at least:

```json
{"id": 12345, "auth_token": "kZoG4GMyPzsl_Ei_nZFSqA"}
```

_id_ - the user's ID, integer

_auth_token_ - the authentication token for the other calls

The object also carries account details (for example language, email, name and roles). They are not part of this reference and may change without notice.

### Errors

HTTP code 400 if login or password is missing (one "is missing" per missing parameter)

```json
{"error":"is missing"}
```

HTTP code 401 if the login or the password is wrong

```json
{"error":"Invalid login or password"}
```

### Examples

```bash
curl -i -H "Accept: application/json" -X POST --data 'login=nosuchuser@example.org&password=j3Sk8nZwp29XpR' 'https://api.leaderssl.com/api/v1/users/signin'

HTTP/1.1 401 Unauthorized
{"error":"Invalid login or password"}


curl -i -H "Accept: application/json" -X POST --data 'login=johndoe@test.com&password=somepassword' 'https://api.leaderssl.com/api/v1/users/signin'

HTTP/1.1 200 OK
{"id":1703,"auth_token":"BUYVWzx7df60ukU9px2-Dg","language":"en", ...}
```

## 2. Products list and prices

### Endpoint

https://api.leaderssl.com/api/v1/products

### Method

GET

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* recommended_prices. Optional. The value EU returns LeaderSSL's end-user prices in EUR instead of your partner prices.

This call is available to partner (reseller) accounts.

### Return

HTTP code 200, a JSON-encoded array of the SSL certificates you can order, with your prices. The example is shortened and its values are illustrative.

```json
[
  {
    "id": 296,
    "name": "Sectigo (Comodo) SSL UCC DV certificate",
    "brand": "comodo",
    "validation_type": "dv",
    "is_ev": false,
    "type": "ucc",
    "issuer": "comodo",
    "prio": 64,
    "prices": [
      {"value": "75.0", "period": 1, "rrp": "147.0"},
      {"value": "136.0", "period": 2, "rrp": "257.25"}
    ],
    "options": [
      {
        "quantity_from": 4,
        "quantity_to": null,
        "type": null,
        "description": "Additional domain (4+)",
        "prices": [{"value": "26.0", "period": 1, "rrp": "30.0"}, {"value": "40.0", "period": 2, "rrp": "50.0"}]
      },
      {
        "quantity_from": null,
        "quantity_to": null,
        "type": "wildcard",
        "description": "Wildcard domain",
        "prices": [{"value": "147.0", "period": 1, "rrp": "147.0"}, {"value": "240.0", "period": 2, "rrp": "240.0"}]
      }
    ],
    "addons": []
  }
]
```

* id - product ID. Use it as nomenclature_id in [5. New order](#5-new-order).
* name - product name in the language of your account.
* brand - the certificate brand: comodo, sectigo, digicert, geotrust, thawte, rapidssl or certum.
* validation_type - the validation type. One of the following values:
    * "dv" - only domain control is validated.
    * "ov" - the organisation is validated against various external sources.
    * "ev" - extended validation of the organisation.
* is_ev - true for extended validation certificates.
* type - the certificate type. One of the following values:
    * "standart" (sic, the API uses this spelling) - protects a single domain.
    * "wildcard" - protects all subdomains of a domain (*.domain.com). Some certificates, for example Sectigo Wildcard, also cover the main domain (domain.com).
    * "ucc" - protects several domains (domain1.com, domain2.com, sub.domain.com).
* issuer - the certificate authority: comodo (Sectigo), sectigo, digicert or certum.
* prio - display order, higher first.
* prices - your price for each period: value (decimal as a string), period (years) and rrp (the recommended end-user price as a string, or null). Prices are net amounts in the currency of your account; VAT is added on the invoice.
* options - extra price options of the certificate: additional domains for multi-domain certificates (quantity_from and quantity_to give the domain range, null means no limit, type null), or a wildcard domain (type "wildcard"). Each option has the same prices structure.
* addons - products that can be added to this one, usually empty.

Code signing, S/MIME and document signing products are not in this list.

### Errors

HTTP code 401 without a valid token. Without any token the message is {"error":"Undefined X-PUBLIC-TOKEN or public_token"}, because this call also accepts a public token.

HTTP code 403 if your account is not a partner account

```json
{"error":"Not authorized for partnership"}
```

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: BUYVWzx7df60ukU9px2-Dg" 'https://api.leaderssl.com/api/v1/products'

HTTP/1.1 200 OK
[{"id":296,"name":"Sectigo (Comodo) SSL UCC DV certificate","brand":"comodo","validation_type":"dv","is_ev":false,"type":"ucc","issuer":"comodo","prio":64,"prices":[{"value":"75.0","period":1,"rrp":"147.0"}, ...
```

## 3. Download ready certificate

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates/{certificate_id}/download

### Method

GET

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* certificate_id. ID of the certificate

### Return

HTTP code 200 and a ZIP archive with the certificate bundle. The file name is the CA order number with the extension .zip.

If the certificate was replaced by a reissue (see [12. Reissue certificate](#12-reissue-certificate)), the download with the original ID returns the issued replacement.

For separate files per server type (nginx, Apache, IIS, Exchange and plain PEM), use [15. Download certificate bundle](#15-download-certificate-bundle).

### Errors

HTTP code 404 if the certificate does not exist or belongs to another account.

HTTP code 422 if the certificate is not issued yet

```json
{"errors":"The certificate is not available"}
```

### Example

```bash
curl -o certificate.zip -H "X-AUTH-TOKEN: h-ioBELRLcg_Z5hqZFyHMA" 'https://api.leaderssl.com/api/v1/ssl_certificates/16278/download'
```

## 4. Certificate status

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates/{certificate_id}/status

### Method

GET

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* certificate_id. ID of the certificate

### Return

HTTP code 200

```json
{
  "certificate": "issued",
  "client": {"status": "new", "description": ""}
}
```

* certificate - the certificate state. One of the following values:
    * new - the order has been prepared but not yet sent to the CA
    * in_progress - the CA is issuing the certificate; domain or organisation validation may be required (see [8. DCV Status](#8-dcv-status))
    * issued - the certificate has been issued and can be [downloaded](#3-download-ready-certificate)
    * expired - the certificate has expired
    * annulled - the order was cancelled or rejected, or the certificate was revoked
    * waiting_for_approval - the CA is waiting for an approval of the order (rare)
    * other - a CA state that does not map to the values above
* client - reserved. At the moment it is always {"status":"new","description":""}.

**How often to poll**

LeaderSSL learns of a state change from the certificate authority: Sectigo and DigiCert push it as it happens, and changes at Certum are picked up within about 5 minutes. Poll a certificate at most once every 5 minutes, and stop once the state is issued, expired or annulled. Polling more often does not speed up the issuance. While the state is in_progress, [8. DCV Status](#8-dcv-status) shows which domains still have to be validated and how.

### Errors

HTTP code 404 if the certificate does not exist or belongs to another account

```json
{"error":"not found"}
```

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: h-ioBELRLcg_Z5hqZFyHMA" 'https://api.leaderssl.com/api/v1/ssl_certificates/16278/status'

{"certificate":"issued","client":{"status":"new","description":""}}
```

## 5. New order

### Endpoint

https://api.leaderssl.com/api/v1/order

### Method

POST

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).

The order is a JSON-encoded object

```json
{
  "order": {
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+31 20 1234567",
      "email": "john@example.com",
      "title": "IT manager",
      "fax": null,
      "company": "Example B.V.",
      "address_1": "Keizersgracht 1",
      "city_name": "Amsterdam",
      "region_name": "Noord-Holland",
      "zip_code": "1015 CC",
      "country_id": "NL",
      "items": [
        {
          "nomenclature_id": 296,
          "days": 365,
          "ssl_server_software_id": 3,
          "dcv_type": "EMAIL",
          "dcv_email": "admin@test.com",
          "domain_name": "test.com",
          "csr": "-----BEGIN CERTIFICATE REQUEST-----\r\nMIIC...\r\n-----END CERTIFICATE REQUEST-----",
          "country_name": "NL",
          "region_name": "Noord-Holland",
          "city_name": "Amsterdam",
          "organization_name": "Test B.V.",
          "organizational_unit": "IT Department",
          "zip_code": "1015 CC",
          "address_1": "Address Line 1",
          "address_2": "Address Line 2",
          "additional_domains": "test2.com,www.test.com",
          "additional_validation_emails": {
              "test2.com": "admin@test2.com",
              "www.test.com": "admin@test.com"
          },
          "unique_value": "dY4bMq2f"
        }
      ]
  }
}
```

#### Parameters description

##### Administrative contact person

All fields are optional. If a field is omitted, the value from your account data is used.

* first_name, last_name, phone, email, title, fax, company, address_1, city_name, region_name, zip_code: strings
* country_id: the country's numeric ID or its ISO 3166-1 alpha-2 code (for example "NL"). The list of countries with IDs and codes is available at GET /api/v1/countries without a token.

##### Certificate details

items must contain at least one certificate; an order without items is rejected with the message "Items can't be blank". Each item has the following fields:

* nomenclature_id: integer, required. ID of the ordered product, the id from [2. Products list and prices](#2-products-list-and-prices)
* days: integer, required. The ordered validity in days, from 60 to 2200. Use 365 for one year, 730 for two years, and so on. The CA issues each certificate for at most about 200 days; the rest of the period is covered by reissues (see [7. Certificates List](#7-certificates-list))
* ssl_server_software_id: integer, required. The server software the certificate is for. Pass 0 to let LeaderSSL choose the default for the CA (an Apache entry). Common values:

    For Sectigo (Comodo) products:
    * 3 - Apache/ModSSL
    * 37 - Microsoft IIS 7.x and later
    * 180 - Linux (Apache/Nginx, etc)
    * 181 - Windows (IIS/Lync/Exchange, etc)
    * 34 - Other

    For DigiCert products (DigiCert, GeoTrust, Thawte and RapidSSL brands):
    * 41 - Apache + MOD SSL
    * 56 - Apache 2
    * 38 - Microsoft IIS (all versions)
    * 182 - Linux (Apache/Nginx, etc)
    * 183 - Windows (IIS/Lync/Exchange, etc)
    * 39 - Other

    For Certum products:
    * 186 - Apache/ModSSL
    * 187 - Microsoft IIS 7.x and later
    * 188 - Other

    The full list for a product is available at GET /api/v1/users/{user_id}/nomenclatures/{nomenclature_id}/ssl_server_softwares without a token; each entry has an id, a code, a name and an issuer. Send the id.
* dcv_type: string. The domain control validation method. One of the following values:
    * EMAIL - an email with a validation code is sent to dcv_email. Accepted for every product.
    * CNAME_CSR_HASH - a DNS CNAME record with a given name and value must be created. Sectigo, DigiCert and Certum products.
    * HTTP_CSR_HASH - a plain-text file with a given name and content must be served from the root of the web server over HTTP. Sectigo, DigiCert and Certum products, not for wildcard names.
    * HTTPS_CSR_HASH - the same file served over HTTPS. Sectigo products, not for wildcard names. DigiCert and Certum treat it as HTTP_CSR_HASH.
    * DNS_TXT_TOKEN - a DNS TXT record with a given value must be created. Sectigo, DigiCert and Certum products. For a Sectigo product it covers the whole order: send it without additional_validation_emails. The value is shown by [8. DCV Status](#8-dcv-status) once the order has been placed; for Sectigo the record is created at `_pki-validation.<domain>`.

    For all other products use EMAIL.
* dcv_email: string. For dcv_type EMAIL: one of the addresses returned by [6. Get DCV Email](#6-get-dcv-email). For a Sectigo product, a DNS TXT value here (DNS_TXT_TOKEN, or Sectigo's own DNSTXTRNDVAL) is rejected with HTTP 422 unless dcv_type is DNS_TXT_TOKEN.
* domain_name: string, required. Fully qualified domain name (common name) of the certificate
* csr: string, required. Certificate Signing Request in PEM format
* country_name: string. ISO 3166-1 alpha-2 code of the organisation's country, required
* region_name: string, required
* city_name: string, required
* organization_name: string, required for OV and EV certificates
* organizational_unit: string
* zip_code: string
* address_1: string
* address_2: string
* unique_value: string, at most 20 Latin letters and digits. It is included in the request token of the HTTP_CSR_HASH, HTTPS_CSR_HASH and CNAME_CSR_HASH methods (Sectigo). If omitted, LeaderSSL generates one.

For multi-domain (ucc) certificates:

* additional_domains: string. Comma-separated list of the additional domains, for example "test.com,test2.com". When it is sent, it alone lists the extra names, and the other names in the CSR are not ordered. When it is omitted or empty:
    * the DNS names in the CSR's subjectAltName are ordered as additional domains, except domain_name, provided the CSR lists domain_name as its common name or in its subjectAltName. A CSR issued for another host adds no names: the order is for domain_name only.
    * those names are validated and billed like additional_domains (see options in [2. Products list and prices](#2-products-list-and-prices)), and each one must pass domain control validation. With dcv_type EMAIL, send an address for each of them in additional_validation_emails.
    * to order only the common name with a CSR that lists more names, send additional_domains equal to domain_name, or use a CSR without those names.
    * an order placed with a public token is a preorder: it takes the names from its CSR when it is approved, together with its price.

    Single-name and wildcard products never take names from the CSR.
* additional_validation_emails: object. The validation email for each additional domain (EMAIL method only). For a Sectigo product, an order with dcv_type DNS_TXT_TOKEN and additional_validation_emails, or with a DNS TXT value (DNS_TXT_TOKEN, or Sectigo's own DNSTXTRNDVAL) inside additional_validation_emails, is rejected with HTTP 422.

```json
    {
      "test.com": "admin@test.com",
      "test2.com": "admin@test2.com"
    }
```

##### Validation rules

* The number of domains (common name plus additional domains) may not exceed what the product allows; wildcard names are counted separately.
* In additional_domains, a host name without a dot (such as `server`) or a private IP address is rejected as internal. The host names in the CSR's subjectAltName are checked the same way, even when they are not ordered. Blocked top-level domains are rejected.
* HTTP_CSR_HASH and HTTPS_CSR_HASH cannot be used for wildcard names.
* dcv_type must be one of the values listed above; any other value is rejected with the message "Dcv type is not included in the list".

### Return

HTTP code 200 if the order was accepted

```json
{"order": 716576, "certificate": 327126, "token": "KLQMwUtPpNB50KMRw16kiLv-..."}
```

* order - integer. ID of the order
* certificate - integer. ID of the certificate. Use it to [check the status](#4-certificate-status) and to [download the certificate](#3-download-ready-certificate)
* token - string. Reference token of the order

### Errors

HTTP code 400 if the order object is missing

```json
{"error":"Required parameter is missing"}
```

HTTP code 403 if your login may not place orders.

HTTP code 422 if the order data is not valid. The errors field lists every problem

```json
{"errors":["City name can't be blank", "Csr can't be blank", "Dcv type is not included in the list"]}
```

## 6. Get DCV Email

### Endpoint

https://api.leaderssl.com/api/v1/dcv_emails

### Method

POST

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* domain_name. The domain name
* provider. Optional. The value symantec returns the addresses accepted by DigiCert; otherwise the addresses accepted by Sectigo are returned.

### Return

HTTP code 200, a JSON-encoded object with the acceptable validation email addresses, grouped by source

```json
{
  "whois": [],
  "level_2": ["admin@test.com", "administrator@test.com", "hostmaster@test.com", "postmaster@test.com", "webmaster@test.com"],
  "level_3": []
}
```

Each group is an empty array, null, or an array of email addresses. The object can be empty ({}) when the CA reports no addresses for the domain. Certum accepts admin@, administrator@, hostmaster@, postmaster@ and webmaster@ of the domain.

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: g65PyAjSCYP0iPHUzxMImg" -X POST --data 'domain_name=test.com' 'https://api.leaderssl.com/api/v1/dcv_emails'
```

## 7. Certificates List

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates

The same list is also served at /api/v1/users/{user_id}/our_ssl_certificates with the same parameters, where user_id is the id returned by the [signin call](#1-authentication); any other user_id answers HTTP code 401 {"error":"Invalid user_id"}. New integrations should use the endpoint above.

### Method

GET

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* page. Optional. Page number, 50 certificates per page. Without it, all certificates are returned in one response.
* scope. Optional, with page: api_issued, api_in_progress or api_annulled to list only certificates in that state.
* q. Optional, with page: text to search in the domain names and organisation names.

When page is used, the response carries an X-Pagination header with a JSON-encoded object: total, total_pages, first_page, last_page, previous_page, next_page, out_of_bounds and offset.

### Return

HTTP code 200, a JSON-encoded array of your certificates. The example values are illustrative.

```json
[
  {
    "internal_number": 123,
    "external_number": 4567,
    "status": {"code": "issued", "description": "issued"},
    "name": "Sectigo (Comodo) SSL UCC DV certificate",
    "domain_name": "domain.com",
    "domain_names": ["www.domain.com", "shop.domain.com"],
    "duration_in_years": 1,
    "public_comment": null,
    "valid_from": "2026-08-31",
    "valid_to": "2027-03-08",
    "subscription_duration": 365,
    "subscription_valid_from": "2026-08-31",
    "subscription_valid_to": "2027-08-31",
    "paid": true,
    "price": "75.0",
    "currency": "EUR",
    "token": "KLQMwUtPpNB50KMRw16kiLv-...",
    "prolongation_token": null,
    "prolonged_id": null,
    "prolonged": false,
    "symantec_reissue": false,
    "dcv_method": "EMAIL",
    "dcv_content": null,
    "all_validation_emails": ["admin@domain.com"],
    "all_domains": ["domain.com", "www.domain.com", "shop.domain.com"]
  }
]
```

* internal_number - ID of the certificate. Use it as certificate_id in the other calls
* external_number - the CA's order number, for reference
* status - code and description carry the same value, the certificate state as in [4. Certificate status](#4-certificate-status). While a cancellation or a reissue is pending the code has a suffix, for example issued_pending_cancel or issued_pending_reissuing
* name - product name
* domain_name - the common name
* domain_names - the additional domains
* duration_in_years - the ordered duration in whole years
* public_comment - comment on the certificate
* valid_from, valid_to - validity period of the current certificate
* subscription_duration - length of the subscription in days for Sectigo multi-year subscriptions, otherwise null
* subscription_valid_from, subscription_valid_to - validity period of the subscription
* paid - true if the certificate has been paid; false or null if not
* price, currency - the price of the certificate (decimal as a string) and its currency
* token - reference token of the order
* prolongation_token - token of the renewal order, if one has been prepared; see [16. Renewal order](#16-renewal-order), also for how to treat the token
* prolonged_id, prolonged - ID of the certificate this one renews (the previous certificate), and whether this certificate is a renewal
* symantec_reissue - internal flag
* dcv_method, dcv_content - the current DCV method and, for file-based methods, the file content to publish; for a DNS_TXT_TOKEN order, dcv_content holds the value of the TXT record
* all_validation_emails - the validation email addresses in use
* all_domains - all domain names of the certificate

**What is a subscription?**

Multi-year SSL subscriptions give you continuous certificate coverage for up to five years at a lower price. Under the CA/Browser Forum rules a certificate is issued for at most about 200 days, so it expires before the paid subscription ends. To stay covered until the end of the subscription, [reissue the certificate](#12-reissue-certificate) before it expires. The reissue is free. It does not extend the paid subscription, so the new certificate can be shorter than the maximum validity period.

Note: install the new certificate after every reissue.

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: g65PyAjSCYP0iPHUzxMImg" 'https://api.leaderssl.com/api/v1/ssl_certificates?page=1&scope=api_issued'
```

## 8. DCV Status

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates/{certificate_id}/dcv

### Method

GET

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* certificate_id. ID of the certificate

### Return

HTTP code 200 while the certificate is in progress

```json
{
  "dcv": {
    "leadertelecom.biz": {
      "sent": true,
      "valid": true,
      "api": true,
      "method": "admin@leadertelecom.biz",
      "status": "Validated",
      "emails": {
        "whois": ["info@leadertelecom.nl"],
        "level_2": ["admin@leadertelecom.biz", "administrator@leadertelecom.biz", "hostmaster@leadertelecom.biz", "postmaster@leadertelecom.biz", "webmaster@leadertelecom.biz"],
        "level_3": []
      }
    }
  }
}
```

For each domain of the certificate the following data is returned:

* sent - boolean. Whether the DCV email has been sent (or the alternative DCV method has been started)
* valid - boolean. True once the domain has been validated
* api - boolean. True when the data comes from the CA, false for the initial local state
* method - the DCV method: the validation email address for EMAIL, otherwise 'HTTP CSR Hash', 'HTTPS CSR Hash', 'CNAME CSR Hash' or 'DNS TXT random value'; null when the certificate authority does not report the method (Certum)
* dcv_method - Sectigo only: the domain's current DCV method as a dcv_type value (EMAIL, HTTP_CSR_HASH, HTTPS_CSR_HASH, CNAME_CSR_HASH or DNS_TXT_TOKEN), or null when it cannot be established (for example in the first minutes after the order is placed)
* status - the validation status reported by the CA
* emails - the acceptable DCV email addresses, as in [6. Get DCV Email](#6-get-dcv-email). Where the certificate authority has issued a DNS TXT value it also holds random_value, the value of the TXT record to create. For Sectigo it is present only for a domain whose dcv_method is DNS_TXT_TOKEN; create the record at `_pki-validation.<domain>` (for a wildcard, without the "*."). The same record at _pki-validation of a parent domain also validates its subdomains
* hashes - Sectigo only: the hashes of the CSR for the file and DNS methods, {"md5": "...", "sha1": "..."}. The sha1 field holds the SHA-256 hash despite its name
* unique_value - Sectigo only: the unique value used in the request token

For Sectigo certificates a unique_value key can also be present at the top level of dcv.

### Errors

HTTP code 422 if the certificate is not in progress

```json
{"success": false, "error": "DCV validation is only available for certificates in the issuing process. Current status: issued", "certificate_status": "issued", "dcv_available": false}
```

HTTP code 422 if the CA could not be reached

```json
{"success": false, "error": "Unable to retrieve DCV validation status"}
```

HTTP code 404 if the certificate does not exist or belongs to another account.

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: Ztu3C--NI6W41g_RdkTtQA" 'https://api.leaderssl.com/api/v1/ssl_certificates/16278/dcv'
```

## 9. Change DCV

Changes the DCV method or email address of a domain and resends the validation email.

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates/{certificate_id}/change_dcv

### Method

POST

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* certificate_id. ID of the certificate
* domain. The domain name to change. Required for multi-domain certificates; if omitted, the main validation email of the certificate is changed
* email. The new DCV email: one of the addresses returned by [8. DCV Status](#8-dcv-status) or [6. Get DCV Email](#6-get-dcv-email), or one of the methods HTTP_CSR_HASH, HTTPS_CSR_HASH (Sectigo only) or CNAME_CSR_HASH

### Return

HTTP code 200, also when the change is refused. Check the success field.

```json
{"success": true, "result": "DCV email has been changed and resent"}
```

* success - true if the change was sent to the CA, false otherwise
* result - string. One of the following values:
    * "DCV email has been changed and resent"
    * "DCV email has been re-sent/ Alt DCV retried" - nothing changed, the current method was resent
    * "DCV email has been changed" - the order has not reached the CA yet; the method is stored for the order
    * "Failed changing DCV email: ..." - with the reason, for example "Can change dcv email only if the certificate has in progress state"

### Errors

HTTP code 403 if your login has no access to certificate actions

```json
{"error": "You do not have permission for this action"}
```

HTTP code 404 if the certificate does not exist or belongs to another account.

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: Ztu3C--NI6W41g_RdkTtQA" -X POST --data 'domain=example.com&email=admin@example.com' 'https://api.leaderssl.com/api/v1/ssl_certificates/22561/change_dcv'

{"success":true,"result":"DCV email has been changed and resent"}
```

## 10. Resend DCV Email

Resends the validation email, or retries the alternative DCV method.

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates/{certificate_id}/resend_dcv

### Method

POST

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* certificate_id. ID of the certificate

### Return

HTTP code 200, also when the resend is refused. Check the success field.

```json
{"success": true, "result": "DCV email has been re-sent/ Alt DCV retried"}
```

* success - true if the email was resent, false otherwise
* result - string. "DCV email has been re-sent/ Alt DCV retried", or "Failed resend DCV email: ..." with the reason. A resend is only possible while the certificate is in progress

### Errors

HTTP code 403 if your login has no access to certificate actions

```json
{"error": "You do not have permission for this action"}
```

HTTP code 404 if the certificate does not exist or belongs to another account.

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: Ztu3C--NI6W41g_RdkTtQA" -X POST 'https://api.leaderssl.com/api/v1/ssl_certificates/22561/resend_dcv'

{"success":true,"result":"DCV email has been re-sent/ Alt DCV retried"}
```

## 11. Account Balance

### Endpoint

https://api.leaderssl.com/api/v1/billing/balance

### Method

GET

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).

### Return

HTTP code 200, JSON-encoded object with five amounts. Each amount is an object with _sum_ (number, rounded to 2 decimals) and _currency_ (string, ISO 4217 code of the account currency). All amounts are customer-facing and include VAT where it applies.

```json
{
  "balance":    {"sum": 1250.0, "currency": "EUR"},
  "reserved":   {"sum": 150.0,  "currency": "EUR"},
  "common":     {"sum": 1100.0, "currency": "EUR"},
  "prepayment": {"sum": 0.0,    "currency": "EUR"},
  "available":  {"sum": 1100.0, "currency": "EUR"}
}
```

* balance - account balance: payments received minus delivered services (acts). Includes money paid for services that are not delivered yet.
* reserved - the unpaid bills of certificates that are being issued or are already issued. The amount stays reserved until those bills are paid, so it does not drop when a certificate is issued.
* common - balance minus reserved. This is the balance shown in the customer portal.
* prepayment - paid prepayment bills that are not assigned to a service yet.
* available - payments that are not assigned to any bill. Can be used to pay new bills.

If the account has no agreement yet, all five amounts are 0.0 EUR (HTTP code 200).

### Errors

HTTP code 401 if the token is missing or invalid

```json
{"error":"error description"}
```

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: Ztu3C--NI6W41g_RdkTtQA" 'https://api.leaderssl.com/api/v1/billing/balance'

{"balance":{"sum":1250.0,"currency":"EUR"},"reserved":{"sum":150.0,"currency":"EUR"},"common":{"sum":1100.0,"currency":"EUR"},"prepayment":{"sum":0.0,"currency":"EUR"},"available":{"sum":1100.0,"currency":"EUR"}}
```

## 12. Reissue certificate

Reissues (re-keys) a certificate within the same order, for example with a new private key, or to stay covered until the end of the subscription when the current certificate expires earlier. A reissue does not create a new order and is not charged.

Do not use [5. New order](#5-new-order) for this: every new order is a separate certificate and is billed again.

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates/{certificate_id}/reissue

### Method

POST

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* certificate_id. ID of the certificate
* csr. New Certificate Signing Request in PEM format ("-----BEGIN CERTIFICATE REQUEST-----" or "-----BEGIN NEW CERTIFICATE REQUEST-----"). Required for Certum certificates, and it must use a new private key: a CSR with the key of the current certificate is rejected. Optional for other certificates: if omitted, the certificate is reissued with its current CSR and private key.
* validation_email. Optional. Domain control validation method for the reissue: one of the emails returned by [8. DCV Status](#8-dcv-status) or [6. Get DCV Email](#6-get-dcv-email), or one of the following values: 'HTTP_CSR_HASH', 'HTTPS_CSR_HASH', 'CNAME_CSR_HASH'. If omitted, the current method is kept. Exception: a Sectigo certificate cannot be reissued with DNS TXT. A Sectigo certificate on DNS_TXT_TOKEN must name another method for every domain, for example an email address (for a multi-domain certificate, with validation_emails for every domain); otherwise the reissue is rejected with HTTP 422.
* validation_emails. Optional, for multi-domain (ucc) certificates. Validation email for each domain, in the same format as additional_validation_emails in [5. New order](#5-new-order)

### Return

HTTP code 200 when the reissue request has been accepted

```json
{"success": true, "result": "The certificate has been reissued"}
```

The new certificate is not ready yet. Repeat the [download](#3-download-ready-certificate) with the same certificate_id (for example every few minutes) until the certificate in the bundle has a different serial number than the previous certificate. If your CSR uses a new private key, also check that the new certificate matches it. While the reissue is processed the download can also answer HTTP 422 (certificate not ready); keep waiting in that case. Do not rely on [4. Certificate status](#4-certificate-status) alone: for some certificate authorities it keeps showing "issued" for the previous certificate while the reissue is processed. If the certificate authority needs to validate the domains again, [8. DCV Status](#8-dcv-status) shows what is required.

To read the serial number: `openssl x509 -noout -serial -in certificate.crt`. To check that a certificate matches your private key, compare the public keys: `openssl x509 -noout -pubkey -in certificate.crt | openssl sha256` and `openssl pkey -pubout -in private.key | openssl sha256` must print the same value.

For some multi-domain Sectigo certificates the reissued certificate gets a new ID. To find it, call [14. Certificate details](#14-certificate-details) with the original ID: its replacement_id field holds the ID of the latest replacement, or null if there is none. Do not look the new certificate up by domain name, because a reissue can change the common name. Use the new ID for all further calls (status, DCV, cancel and the next reissue); a reissue request for the original ID is rejected. Only the two download calls (sections 3 and 15) work with both IDs: with the original ID they return the new certificate as soon as it is issued.

### Errors

HTTP code 422 if the certificate cannot be reissued. The error field explains why.

```json
{"success": false, "error": "error description"}
```

HTTP code 403 if your login has no access to certificate actions

```json
{"error": "You do not have permission for this action"}
```

HTTP code 404 if the certificate does not exist or belongs to another account.

### Rules

* Only certificates in the state new, in_progress, waiting_for_approval or issued can be reissued; expired and annulled certificates cannot.
* Code signing certificates cannot be reissued.
* The common name of the new CSR must be one of the domains of the certificate, and the number of domains cannot grow. For a wildcard certificate (*.example.com) the bare domain (example.com) is also accepted and is not counted as an extra domain. Multi-domain Sectigo certificates may change domains, up to the current number of domains or 3, whichever is larger.
* Reissue is not available during the last 30 days of the subscription. Order a new certificate instead.
* Certum certificates require a new CSR with a new private key for every reissue; reusing a key is rejected.
* Only one reissue can be in progress at a time. Wait until a reissue is finished (see the check above) before you request the next one.

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: Ztu3C--NI6W41g_RdkTtQA" -X POST --data-urlencode 'csr@new.csr' 'https://api.leaderssl.com/api/v1/ssl_certificates/22561/reissue'

{"success":true,"result":"The certificate has been reissued"}
```

## 13. Cancel certificate

Requests the cancellation of a certificate. The request is sent to LeaderSSL staff, who process it, so the certificate is not cancelled instantly. A certificate that has not been issued yet can be cancelled at any time. An issued certificate can be cancelled within 28 days of issuance.

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates/{certificate_id}/cancel

### Method

POST

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* certificate_id. ID of the certificate

### Return

HTTP code 200, also when the cancellation is refused. Check the success field.

```json
{"success": true, "result": "The cancellation order has been sent"}
```

* success - true if the cancellation request has been sent, false otherwise.
* result - string. One of the following values:
    * "The cancellation order has been sent"
    * "Cannot cancel a certificate that was issued more than 28 days ago"
    * "The certificate is already cancelled" (also returned when a cancellation has already been requested)

### Errors

HTTP code 403 if your login has no access to certificate actions

```json
{"error": "You do not have permission for this action"}
```

HTTP code 404 if the certificate does not exist or belongs to another account.

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: Ztu3C--NI6W41g_RdkTtQA" -X POST 'https://api.leaderssl.com/api/v1/ssl_certificates/22561/cancel'

{"success":true,"result":"The cancellation order has been sent"}
```

## 14. Certificate details

Returns one certificate with its order data, validation data, dates, price and status.

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates/{certificate_id}

### Method

GET

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* certificate_id. ID of the certificate

### Return

HTTP code 200, a JSON-encoded object with about 100 fields. The fields below are stable; the others (contact persons, organisation address, internal flags) may change without notice. The example is shortened and its values are illustrative.

```json
{
  "id": 327126,
  "status": {"certificate": "issued", "client": {"status": "new", "description": ""}},
  "external_number": "2407804752",
  "common_name": "domain.com",
  "additional_domains": "www.domain.com,shop.domain.com",
  "all_domains": ["domain.com", "www.domain.com", "shop.domain.com"],
  "valid_from": "2026-08-31",
  "valid_to": "2027-03-08",
  "subscription_duration": 365,
  "subscription_valid_from": "2026-08-31",
  "subscription_valid_to": "2027-08-31",
  "replacement_id": null,
  "prolonged_id": null,
  "dcv_method": "EMAIL",
  "dcv_content": null,
  "validation_email": "admin@domain.com",
  "additional_validation_emails": {"www.domain.com": "admin@domain.com", "shop.domain.com": "admin@domain.com"},
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "nomenclature_id": 296,
  "name": "Sectigo (Comodo) SSL UCC DV certificate",
  "price": 90.75,
  "price_includes_vat": true,
  "currency": "EUR",
  "payment_status": "paid",
  "unpaid": false
}
```

* id - ID of the certificate
* status - the state as in [4. Certificate status](#4-certificate-status). Unlike that call, certificate carries the suffix of [7. Certificates List](#7-certificates-list) while a cancellation or a reissue is pending, for example issued_pending_reissuing
* external_number - the CA's order number (a string), null until the order has reached the CA
* common_name - the common name
* additional_domains - the additional domains as entered in the order, separated by commas or line breaks; use all_domains for a parsed list
* all_domains - all domain names of the certificate
* valid_from, valid_to - validity period of the current certificate; null while no certificate has been issued yet
* subscription_duration - length of the subscription in days for Sectigo multi-year subscriptions, otherwise null
* subscription_valid_from, subscription_valid_to - validity period of the subscription
* replacement_id - ID of the latest replacement after a reissue that created a new ID (see [12. Reissue certificate](#12-reissue-certificate)), otherwise null
* prolonged_id - ID of the certificate this one renews (the previous certificate), otherwise null
* dcv_method, dcv_content - the current DCV method (EMAIL, HTTP_CSR_HASH, HTTPS_CSR_HASH, CNAME_CSR_HASH or DNS_TXT_TOKEN) and, for file-based methods, the file content to publish; for a DNS_TXT_TOKEN order, dcv_content holds the value of the TXT record
* validation_email - the validation email address of the common name; for a Sectigo certificate ordered with an alternative method it holds the method name instead
* additional_validation_emails - the validation email address of each additional domain
* csr - the Certificate Signing Request of the current certificate, PEM
* nomenclature_id, name - ID and name of the product, as in [2. Products list and prices](#2-products-list-and-prices)
* price, price_includes_vat, currency - the amount due for the certificate as a number, whether it includes VAT, and its currency. Unlike price in [7. Certificates List](#7-certificates-list) this amount includes VAT when VAT applies to your account; it is null when no price is known
* payment_status - paid, unpaid, or not_payable (no price, or a cancelled order)
* unpaid - true while the certificate is billed and the bill is not paid

### Errors

HTTP code 404 if the certificate does not exist or belongs to another account

```json
{"id": null, "error": "An invalid certificate ID was provided for this account"}
```

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: h-ioBELRLcg_Z5hqZFyHMA" 'https://api.leaderssl.com/api/v1/ssl_certificates/16278'

{"id":16278,"name":"Sectigo (Comodo) SSL UCC DV certificate","duration":365, ...}
```

## 15. Download certificate bundle

Downloads the issued certificate and its chain as separate files for the common server types. The files are fetched from the certificate authority for each call. [3. Download ready certificate](#3-download-ready-certificate) returns the CA's own archive instead.

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates/{certificate_id}/download_bundle

### Method

GET

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* certificate_id. ID of the certificate. If the certificate was replaced by a reissue (see [12. Reissue certificate](#12-reissue-certificate)), the call with the original ID returns the bundle of the issued replacement, as [3. Download ready certificate](#3-download-ready-certificate) does.

### Return

HTTP code 200 and a ZIP archive (Content-Type application/zip) named leaderssl_OSC-{certificate_id}.zip with:

* README.txt - which folder to use for which server software
* nginx/fullchain.crt - the certificate followed by the intermediate certificates
* apache/certificate.crt and apache/ca_bundle.crt - the certificate, and the intermediate certificates
* iis/certificate.p7b - PKCS#7 file with the certificate, the intermediate and the root certificates
* pem/{common_name}.pem, pem/chain.pem, pem/root.pem, pem/fullchain.pem, pem/ca-bundle.pem - the certificate, the intermediate certificates, the root certificate, the certificate with the intermediates, and the intermediates with the root
* exchange/{name}.crt - one file per certificate, named after its common name

Each folder has a README.txt with installation steps. The private key is not included.

### Errors

HTTP code 404 if the certificate does not exist or belongs to another account

```json
{"errors":"Certificate not found"}
```

HTTP code 422 if the certificate authority has not issued the certificate yet, or does not provide it for download

```json
{"errors":"Certificate PEM data is not available"}
```

HTTP code 422 if the archive could not be built, or the certificate authority could not be reached: {"errors":"Failed to build certificate bundle"} or {"errors":"Failed to retrieve certificate PEM data"}

### Example

```bash
curl -o bundle.zip -H "X-AUTH-TOKEN: h-ioBELRLcg_Z5hqZFyHMA" 'https://api.leaderssl.com/api/v1/ssl_certificates/16278/download_bundle'
```

## 16. Renewal order

Prepares the renewal order for a certificate and returns its token. The renewal is a new order for the same product and domains at your current price, placed in the LeaderSSL order site; nothing is ordered or billed until that order is completed. LeaderSSL prepares the same order itself about 30 days before the certificate expires (its token then appears as prolongation_token in [7. Certificates List](#7-certificates-list)); this call prepares it earlier.

### Endpoint

https://api.leaderssl.com/api/v1/ssl_certificates/{certificate_id}/prolong

### Method

POST

### Parameters

* auth_token. Authentication token returned by the [signin call](#1-authentication). Send it in the X-AUTH-TOKEN HTTP header, or as the auth_token query parameter (deprecated).
* certificate_id. ID of the certificate

### Return

HTTP code 200

```json
{"prolongation_token": "KLQMwUtPpNB50KMRw16kiLv-..."}
```

* prolongation_token - string, or null when no renewal order exists yet and none can be prepared: the certificate has already been renewed, it was replaced by a reissue, it has no order to renew, or it belongs to a Sectigo multi-year subscription that ends more than 3 months from now (reissue instead, see [12. Reissue certificate](#12-reissue-certificate)). An order that was prepared earlier is returned in any case

Repeated calls return the same token. The order is completed at https://www.leaderssl.com/lead/continue_order/{prolongation_token}.

**Treat the token as a credential.** Opening that link signs the visitor in to www.leaderssl.com as your account. Do not pass the link to your customers or to third parties: complete the renewal yourself, or renew the certificate with a [new order](#5-new-order).

### Errors

HTTP code 403 if your login may not place orders

```json
{"error": "You do not have permission for this action"}
```

HTTP code 404 if the certificate does not exist or belongs to another account.

### Example

```bash
curl -i -H "Accept: application/json" -H "X-AUTH-TOKEN: Ztu3C--NI6W41g_RdkTtQA" -X POST 'https://api.leaderssl.com/api/v1/ssl_certificates/22561/prolong'

{"prolongation_token":"KLQMwUtPpNB50KMRw16kiLv-..."}
```