LeaderSSL Partner API Reference

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) 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.

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

Machine-readable versions

1. Authentication

Endpoint

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

Method

POST

Parameters

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:

{"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)

{"error":"is missing"}

HTTP code 401 if the login or the password is wrong

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

Examples

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

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.

[
  {
    "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": []
  }
]

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

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

Example

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

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), 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.

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

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

Example

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

Return

HTTP code 200

{
  "certificate": "issued",
  "client": {"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 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

{"error":"not found"}

Example

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

The order is a JSON-encoded object

{
  "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.

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:

For multi-domain (ucc) certificates:

    {
      "test.com": "admin@test.com",
      "test2.com": "admin@test2.com"
    }
Validation rules

Return

HTTP code 200 if the order was accepted

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

Errors

HTTP code 400 if the order object is missing

{"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

{"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

Return

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

{
  "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

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; any other user_id answers HTTP code 401 {"error":"Invalid user_id"}. New integrations should use the endpoint above.

Method

GET

Parameters

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.

[
  {
    "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"]
  }
]

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 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

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

Return

HTTP code 200 while the certificate is in progress

{
  "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:

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

{"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

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

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

Example

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

Return

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

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

Errors

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

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

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

Example

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

Return

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

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

Errors

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

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

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

Example

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

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.

{
  "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"}
}

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

{"error":"error description"}

Example

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 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

Return

HTTP code 200 when the reissue request has been accepted

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

The new certificate is not ready yet. Repeat the download 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 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 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 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.

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

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

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

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

Rules

Example

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

Return

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

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

Errors

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

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

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

Example

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

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.

{
  "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
}

Errors

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

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

Example

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 returns the CA's own archive instead.

Endpoint

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

Method

GET

Parameters

Return

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

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

{"errors":"Certificate not found"}

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

{"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

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); this call prepares it earlier.

Endpoint

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

Method

POST

Parameters

Return

HTTP code 200

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

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.

Errors

HTTP code 403 if your login may not place orders

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

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

Example

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-..."}