{ "openapi": "3.1.0", "info": { "title": "LeaderSSL Partner API", "version": "1.0.0", "description": "API for LeaderSSL partners (resellers): list the SSL products and your prices, order certificates, run domain control validation (DCV), download, reissue and cancel certificates, and read the account balance. The full reference with examples is https://api.leaderssl.com/ (Markdown: https://api.leaderssl.com/doc.md).\n\nAuthentication: sign in with POST /api/v1/users/signin and send the returned auth_token in the X-AUTH-TOKEN header. Store the token and sign in again only when a call answers HTTP 401.\n\nEvery POST /api/v1/order is a new certificate order and is billed. To get a new certificate for an existing order (a new key, or coverage until the end of the subscription), use POST /api/v1/ssl_certificates/{certificate_id}/reissue, which is not charged.\n\nChange DCV, resend DCV and cancel answer HTTP 200 also when the action is refused: always check the success field." }, "externalDocs": { "description": "LeaderSSL Partner API Reference", "url": "https://api.leaderssl.com/" }, "servers": [ { "url": "https://api.leaderssl.com" } ], "security": [ { "authToken": [] } ], "paths": { "/api/v1/users/signin": { "post": { "operationId": "signIn", "summary": "Sign in and get the authentication token", "description": "A signin can return a new token, and then the previous token stops working. Store the token and sign in again only when a call answers HTTP 401.", "security": [], "externalDocs": { "url": "https://api.leaderssl.com/#1-authentication" }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SigninRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SigninRequest" } } } }, "responses": { "200": { "description": "The credentials. The object also carries account details that are not part of this reference.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The user's ID" }, "auth_token": { "type": "string", "description": "The token for the X-AUTH-TOKEN header of the other calls" } } }, "example": { "id": 1703, "auth_token": "BUYVWzx7df60ukU9px2-Dg" } } } }, "400": { "description": "login or password is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "is missing" } } } }, "401": { "description": "The login or the password is wrong", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid login or password" } } } } } } }, "/api/v1/products": { "get": { "operationId": "listProducts", "summary": "List the SSL products you can order, with your prices", "description": "Available to partner (reseller) accounts. Prices are net amounts in the currency of your account; VAT is added on the invoice. Code signing, S/MIME and document signing products are not in this list.", "externalDocs": { "url": "https://api.leaderssl.com/#2-products-list-and-prices" }, "parameters": [ { "name": "recommended_prices", "in": "query", "required": false, "description": "EU returns LeaderSSL's end-user prices in EUR instead of your partner prices", "schema": { "type": "string", "enum": [ "EU" ] } } ], "responses": { "200": { "description": "The SSL certificates you can order", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Your account is not a partner account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Not authorized for partnership" } } } } } } }, "/api/v1/ssl_certificates/{certificate_id}/download": { "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "get": { "operationId": "downloadCertificate", "summary": "Download the issued certificate as a ZIP archive", "description": "The file name is the CA order number with the extension .zip. If the certificate was replaced by a reissue, the download with the original ID returns the issued replacement.", "externalDocs": { "url": "https://api.leaderssl.com/#3-download-ready-certificate" }, "responses": { "200": { "description": "ZIP archive with the certificate bundle", "content": { "application/zip": {} } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The certificate is not issued yet", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "string" } } }, "example": { "errors": "The certificate is not available" } } } } } } }, "/api/v1/ssl_certificates/{certificate_id}/status": { "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "get": { "operationId": "getCertificateStatus", "summary": "Get the state of a certificate", "description": "While a reissue is processed, some certificate authorities keep showing issued for the previous certificate; see reissueCertificate for how to tell that a reissue is finished. Sectigo and DigiCert push a state change as it happens and changes at Certum are picked up within about 5 minutes: poll a certificate at most once every 5 minutes, stop once the state is issued, expired or annulled, and read getDcvStatus while it is in_progress.", "externalDocs": { "url": "https://api.leaderssl.com/#4-certificate-status" }, "responses": { "200": { "description": "The certificate state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateStatus" }, "example": { "certificate": "issued", "client": { "status": "new", "description": "" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The certificate does not exist or belongs to another account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not found" } } } } } } }, "/api/v1/order": { "post": { "operationId": "createOrder", "summary": "Order a new certificate (billed)", "description": "Every call creates a new certificate order, and every new order is billed. Do not call it again to reissue or re-key a certificate of an existing order: use reissueCertificate. The product ID (nomenclature_id) comes from listProducts, the validation email (dcv_email) from getDcvEmails.", "externalDocs": { "url": "https://api.leaderssl.com/#5-new-order" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } } }, "responses": { "200": { "description": "The order was accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "integer", "description": "ID of the order" }, "certificate": { "type": "integer", "description": "ID of the certificate (certificate_id in the other calls)" }, "token": { "type": [ "string", "null" ], "description": "Reference token of the order" } } }, "example": { "order": 716576, "certificate": 327126, "token": "KLQMwUtPpNB50KMRw16kiLv-..." } } } }, "400": { "description": "The order object is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Required parameter is missing" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "The order data is not valid. errors lists every problem.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } }, "example": { "errors": [ "City name can't be blank", "Csr can't be blank", "Dcv type is not included in the list" ] } } } } } } }, "/api/v1/dcv_emails": { "post": { "operationId": "getDcvEmails", "summary": "List the acceptable DCV email addresses of a domain", "description": "Certum accepts admin@, administrator@, hostmaster@, postmaster@ and webmaster@ of the domain.", "externalDocs": { "url": "https://api.leaderssl.com/#6-get-dcv-email" }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "domain_name" ], "properties": { "domain_name": { "type": "string", "description": "The domain name" }, "provider": { "type": "string", "enum": [ "symantec" ], "description": "symantec returns the addresses accepted by DigiCert; otherwise the addresses accepted by Sectigo are returned" } } } } } }, "responses": { "200": { "description": "The acceptable validation email addresses, grouped by source. The object can be empty when the CA reports no addresses for the domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DcvEmails" }, "example": { "whois": [], "level_2": [ "admin@test.com", "administrator@test.com", "hostmaster@test.com", "postmaster@test.com", "webmaster@test.com" ], "level_3": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/ssl_certificates": { "get": { "operationId": "listCertificates", "summary": "List your certificates", "description": "For a multi-year subscription each certificate is issued for at most about 200 days, so it expires before the paid subscription ends. To stay covered until subscription_valid_to, reissue the certificate (reissueCertificate) before it expires, and install the new certificate after every reissue. 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 signIn; any other user_id answers 401 {\"error\":\"Invalid user_id\"}.", "externalDocs": { "url": "https://api.leaderssl.com/#7-certificates-list" }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, 50 certificates per page. Without it, all certificates are returned in one response.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "scope", "in": "query", "required": false, "description": "With page: list only certificates in that state", "schema": { "type": "string", "enum": [ "api_issued", "api_in_progress", "api_annulled" ] } }, { "name": "q", "in": "query", "required": false, "description": "With page: text to search in the domain names and organisation names", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Your certificates", "headers": { "X-Pagination": { "description": "Sent when page is used: a JSON-encoded object with total, total_pages, first_page, last_page, previous_page, next_page, out_of_bounds and offset", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Certificate" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/ssl_certificates/{certificate_id}/dcv": { "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "get": { "operationId": "getDcvStatus", "summary": "Get the domain control validation state of each domain", "externalDocs": { "url": "https://api.leaderssl.com/#8-dcv-status" }, "responses": { "200": { "description": "The DCV state, while the certificate is in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DcvStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The certificate is not in progress, or the CA could not be reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "certificate_status": { "type": "string" }, "dcv_available": { "type": "boolean" } } }, "example": { "success": false, "error": "DCV validation is only available for certificates in the issuing process. Current status: issued", "certificate_status": "issued", "dcv_available": false } } } } } } }, "/api/v1/ssl_certificates/{certificate_id}/change_dcv": { "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "post": { "operationId": "changeDcv", "summary": "Change the DCV method or email of a domain and resend the validation", "externalDocs": { "url": "https://api.leaderssl.com/#9-change-dcv" }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "email" ], "properties": { "domain": { "type": "string", "description": "The domain name to change. Required for multi-domain certificates; if omitted, the main validation email of the certificate is changed." }, "email": { "type": "string", "description": "The new DCV email (an address from getDcvStatus or getDcvEmails), or one of the methods HTTP_CSR_HASH, HTTPS_CSR_HASH (Sectigo only) or CNAME_CSR_HASH" } } } } } }, "responses": { "200": { "description": "Also when the change is refused: check success. result is \"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), or \"Failed changing DCV email: ...\" with the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionResult" }, "example": { "success": true, "result": "DCV email has been changed and resent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/ssl_certificates/{certificate_id}/resend_dcv": { "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "post": { "operationId": "resendDcvEmail", "summary": "Resend the validation email, or retry the alternative DCV method", "description": "A resend is only possible while the certificate is in progress.", "externalDocs": { "url": "https://api.leaderssl.com/#10-resend-dcv-email" }, "responses": { "200": { "description": "Also when the resend is refused: check success. result is \"DCV email has been re-sent/ Alt DCV retried\", or \"Failed resend DCV email: ...\" with the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionResult" }, "example": { "success": true, "result": "DCV email has been re-sent/ Alt DCV retried" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/billing/balance": { "get": { "operationId": "getBalance", "summary": "Get the account balance", "description": "All amounts are customer-facing and include VAT where it applies. If the account has no agreement yet, all five amounts are 0.0 EUR.", "externalDocs": { "url": "https://api.leaderssl.com/#11-account-balance" }, "responses": { "200": { "description": "Five amounts in the account currency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "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" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/ssl_certificates/{certificate_id}/reissue": { "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "post": { "operationId": "reissueCertificate", "summary": "Reissue (re-key) a certificate within the same order, free of charge", "description": "A reissue does not create a new order and is not charged. Use it instead of createOrder for a new private key, or to stay covered until the end of the subscription when the current certificate expires earlier.\n\nThe new certificate is not ready when this call returns. Repeat downloadCertificate with the same certificate_id until the certificate in the bundle has a different serial number than the previous one (and, if your CSR uses a new private key, matches that key). Do not rely on getCertificateStatus alone. If the certificate authority needs to validate the domains again, getDcvStatus shows what is required.\n\nFor some multi-domain Sectigo certificates the reissued certificate gets a new ID: read replacement_id from getCertificate with the original ID, and use the new ID for all further calls except downloadCertificate and downloadCertificateBundle, which work with both IDs.\n\nRules: only certificates in the state new, in_progress, waiting_for_approval or issued can be reissued; code signing certificates cannot. Reissue is not available during the last 30 days of the subscription. Only one reissue can be in progress at a time. Certum certificates require a new CSR with a new private key for every reissue. Sectigo certificates 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, with validation_emails for every domain of a multi-domain certificate), otherwise the reissue is rejected with HTTP 422.", "externalDocs": { "url": "https://api.leaderssl.com/#12-reissue-certificate" }, "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "csr": { "type": "string", "description": "New Certificate Signing Request in PEM format. Required for Certum certificates, with a new private key. Optional for other certificates: if omitted, the certificate is reissued with its current CSR and private key." }, "validation_email": { "type": "string", "description": "DCV method for the reissue: an email from getDcvStatus or getDcvEmails, or HTTP_CSR_HASH, HTTPS_CSR_HASH or CNAME_CSR_HASH. If omitted, the current method is kept, except for a Sectigo certificate on DNS_TXT_TOKEN, which must name another method for every domain: DNS TXT is not accepted for a Sectigo reissue." }, "validation_emails": { "type": "object", "description": "Multi-domain certificates: the validation email for each domain, as additional_validation_emails in createOrder", "additionalProperties": { "type": "string" } } } }, "encoding": { "validation_emails": { "style": "deepObject", "explode": true } } } } }, "responses": { "200": { "description": "The reissue request has been accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionResult" }, "example": { "success": true, "result": "The certificate has been reissued" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The certificate cannot be reissued. error explains why.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } } }, "example": { "success": false, "error": "error description" } } } } } } }, "/api/v1/ssl_certificates/{certificate_id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "post": { "operationId": "cancelCertificate", "summary": "Request the cancellation of a certificate", "description": "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 within 28 days of issuance.", "externalDocs": { "url": "https://api.leaderssl.com/#13-cancel-certificate" }, "responses": { "200": { "description": "Also when the cancellation is refused: check success. \"The certificate is already cancelled\" is also returned when a cancellation has already been requested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "result": { "type": "string", "enum": [ "The cancellation order has been sent", "Cannot cancel a certificate that was issued more than 28 days ago", "The certificate is already cancelled" ] } } }, "example": { "success": true, "result": "The cancellation order has been sent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/ssl_certificates/{certificate_id}": { "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ], "get": { "operationId": "getCertificate", "summary": "Get one certificate with its order data, validation data, dates, price and status", "description": "After a reissue that created a new ID, replacement_id holds the latest replacement; do not look a reissued certificate up by domain name, because a reissue can change the common name. Use the new ID for status, DCV, cancel and further reissue calls.", "externalDocs": { "url": "https://api.leaderssl.com/#14-certificate-details" }, "responses": { "200": { "description": "The certificate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateDetails" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The certificate does not exist or belongs to another account", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "null" }, "error": { "type": "string" } } }, "example": { "id": null, "error": "An invalid certificate ID was provided for this account" } } } } } } }, "/api/v1/ssl_certificates/{certificate_id}/download_bundle": { "get": { "operationId": "downloadCertificateBundle", "summary": "Download the issued certificate and its chain as separate files per server type", "description": "ZIP archive named leaderssl_OSC-{certificate_id}.zip with the folders nginx/, apache/, iis/, pem/ and exchange/, each with a README.txt; the private key is not included. The files are fetched from the certificate authority for each call. If the certificate was replaced by a reissue, the call with the original ID returns the bundle of the issued replacement, as downloadCertificate does.", "externalDocs": { "url": "https://api.leaderssl.com/#15-download-certificate-bundle" }, "responses": { "200": { "description": "ZIP archive with the certificate files", "content": { "application/zip": {} } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The certificate does not exist or belongs to another account", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "string" } } }, "example": { "errors": "Certificate not found" } } } }, "422": { "description": "The certificate authority has not issued the certificate yet or does not provide it for download, the archive could not be built, or the certificate authority could not be reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "string", "enum": [ "Certificate PEM data is not available", "Failed to build certificate bundle", "Failed to retrieve certificate PEM data" ] } } }, "example": { "errors": "Certificate PEM data is not available" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ] }, "/api/v1/ssl_certificates/{certificate_id}/prolong": { "post": { "operationId": "createRenewalOrder", "summary": "Prepare the renewal order of a certificate and get its token", "description": "Returns the token of the renewal order, preparing the order if none exists: 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 at https://www.leaderssl.com/lead/continue_order/{prolongation_token}. LeaderSSL prepares the same order itself about 30 days before the certificate expires. Treat the token as a credential: opening that link signs the visitor in to www.leaderssl.com as your account, so do not pass it to customers or third parties.", "externalDocs": { "url": "https://api.leaderssl.com/#16-renewal-order" }, "responses": { "200": { "description": "prolongation_token is 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). An order prepared earlier is returned in any case.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prolongation_token": { "type": [ "string", "null" ] } } }, "example": { "prolongation_token": "KLQMwUtPpNB50KMRw16kiLv-..." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "parameters": [ { "$ref": "#/components/parameters/CertificateId" } ] } }, "components": { "securitySchemes": { "authToken": { "type": "apiKey", "in": "header", "name": "X-AUTH-TOKEN", "description": "The auth_token returned by POST /api/v1/users/signin" } }, "parameters": { "CertificateId": { "name": "certificate_id", "in": "path", "required": true, "description": "ID of the certificate: internal_number in listCertificates, or certificate in the createOrder response", "schema": { "type": "integer" } } }, "responses": { "Unauthorized": { "description": "The token is missing or not valid. Sign in again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid X-AUTH-TOKEN or auth_token" } } } }, "Forbidden": { "description": "Your login may not perform the action, for example a billing-only login", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "You do not have permission for this action" } } } }, "NotFound": { "description": "The certificate does not exist or belongs to another account. The body is not meant to be parsed." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "ActionResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "result": { "type": "string" } } }, "SigninRequest": { "type": "object", "required": [ "login", "password" ], "properties": { "login": { "type": "string", "description": "Your account login (email address)" }, "password": { "type": "string", "description": "Your account password" } } }, "Price": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "description": "Your price, a decimal as a string (net, in the currency of your account)" }, "period": { "type": [ "integer", "null" ], "description": "Period in years" }, "rrp": { "type": [ "string", "null" ], "description": "Recommended end-user price as a string, or null" } } }, "Product": { "type": "object", "properties": { "id": { "type": "integer", "description": "Product ID. Use it as nomenclature_id in createOrder." }, "name": { "type": [ "string", "null" ], "description": "Product name in the language of your account" }, "brand": { "type": [ "string", "null" ], "description": "Certificate brand, for example comodo, sectigo, digicert, geotrust, thawte, rapidssl or certum" }, "validation_type": { "type": [ "string", "null" ], "enum": [ "dv", "ov", "ev", null ] }, "is_ev": { "type": [ "boolean", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "standart", "wildcard", "ucc", null ], "description": "standart (sic) protects a single domain, wildcard all subdomains of a domain, ucc several domains" }, "issuer": { "type": [ "string", "null" ], "description": "Certificate authority, for example comodo (Sectigo), sectigo, digicert or certum" }, "prio": { "type": [ "integer", "null" ], "description": "Display order, higher first" }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "options": { "type": "array", "description": "Additional domains of multi-domain certificates (type null, quantity_from and quantity_to give the range, null means no limit), or a wildcard domain (type wildcard)", "items": { "type": "object", "properties": { "quantity_from": { "type": [ "integer", "null" ] }, "quantity_to": { "type": [ "integer", "null" ] }, "type": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } } } } }, "addons": { "type": "array", "description": "Products that can be added to this one, usually empty", "items": {} } } }, "OrderRequest": { "type": "object", "required": [ "order" ], "properties": { "order": { "type": "object", "description": "The administrative contact fields are optional; an omitted field takes the value from your account data.", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "title": { "type": "string" }, "fax": { "type": [ "string", "null" ] }, "company": { "type": "string" }, "address_1": { "type": "string" }, "city_name": { "type": "string" }, "region_name": { "type": "string" }, "zip_code": { "type": "string" }, "country_id": { "type": [ "integer", "string" ], "description": "The country's numeric ID or its ISO 3166-1 alpha-2 code (for example NL). The list is available at GET /api/v1/countries without a token." }, "items": { "type": "array", "minItems": 1, "description": "The certificates to order, at least one; an order without items is rejected with HTTP 422 (\"Items can't be blank\")", "items": { "$ref": "#/components/schemas/OrderItem" } } }, "required": [ "items" ] } } }, "OrderItem": { "type": "object", "required": [ "nomenclature_id", "days", "ssl_server_software_id", "domain_name", "csr", "country_name", "region_name", "city_name" ], "properties": { "nomenclature_id": { "type": "integer", "description": "ID of the ordered product, the id from listProducts" }, "days": { "type": "integer", "minimum": 60, "maximum": 2200, "description": "Ordered validity in days: 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." }, "ssl_server_software_id": { "type": "integer", "description": "Server software the certificate is for; 0 lets LeaderSSL choose the default for the CA. The list for a product is available at GET /api/v1/users/{user_id}/nomenclatures/{nomenclature_id}/ssl_server_softwares without a token." }, "dcv_type": { "type": "string", "enum": [ "EMAIL", "CNAME_CSR_HASH", "HTTP_CSR_HASH", "HTTPS_CSR_HASH", "DNS_TXT_TOKEN" ], "description": "EMAIL is accepted for every product. CNAME_CSR_HASH and HTTP_CSR_HASH: Sectigo, DigiCert and Certum products. HTTPS_CSR_HASH: Sectigo products; DigiCert and Certum treat it as HTTP_CSR_HASH. DNS_TXT_TOKEN: Sectigo, DigiCert and Certum products; for a Sectigo product it covers the whole order and is rejected with HTTP 422 together with additional_validation_emails. HTTP_CSR_HASH and HTTPS_CSR_HASH are not accepted for wildcard names. For all other products use EMAIL. Any other value is rejected with HTTP 422 (\"Dcv type is not included in the list\")." }, "dcv_email": { "type": "string", "description": "For dcv_type EMAIL: one of the addresses returned by getDcvEmails. For a Sectigo product a DNS TXT value (DNS_TXT_TOKEN, or Sectigo's own DNSTXTRNDVAL) is rejected with HTTP 422 unless dcv_type is DNS_TXT_TOKEN." }, "domain_name": { "type": "string", "description": "Fully qualified domain name (common name) of the certificate" }, "csr": { "type": "string", "description": "Certificate Signing Request in PEM format" }, "country_name": { "type": "string", "description": "ISO 3166-1 alpha-2 code of the organisation's country" }, "region_name": { "type": "string" }, "city_name": { "type": "string" }, "organization_name": { "type": "string", "description": "Required for OV and EV certificates" }, "organizational_unit": { "type": "string" }, "zip_code": { "type": "string" }, "address_1": { "type": "string" }, "address_2": { "type": "string" }, "additional_domains": { "type": "string", "description": "Multi-domain (ucc) certificates: comma-separated list of the additional domains. When sent, it alone lists the extra names and the other names in the CSR are not ordered (a host name without a dot in the CSR, such as server, is still rejected). When omitted or empty, the DNS names in the CSR's subjectAltName other than domain_name are ordered, provided the CSR lists domain_name as its common name or in its subjectAltName; a CSR issued for another host adds no names. Those names are validated and billed like additional_domains, 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. A preorder (an order placed with a public token) takes its CSR names when it is approved, together with its price. Single-name and wildcard products never take names from the CSR." }, "additional_validation_emails": { "type": "object", "description": "Multi-domain (ucc) certificates, EMAIL method: the validation email for each additional domain. For a Sectigo product a DNS TXT value here (DNS_TXT_TOKEN, or Sectigo's own DNSTXTRNDVAL) is rejected with HTTP 422.", "additionalProperties": { "type": "string" } }, "unique_value": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z0-9]+$", "description": "Included in the request token of the CSR hash methods (Sectigo). If omitted, LeaderSSL generates one." } } }, "CertificateStatus": { "type": "object", "properties": { "certificate": { "type": [ "string", "null" ], "enum": [ "new", "in_progress", "issued", "expired", "annulled", "waiting_for_approval", "other", null ] }, "client": { "type": "object", "description": "Reserved. At the moment always {\"status\": \"new\", \"description\": \"\"}.", "properties": { "status": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } } } } }, "Certificate": { "type": "object", "properties": { "internal_number": { "type": "integer", "description": "ID of the certificate. Use it as certificate_id in the other calls." }, "external_number": { "type": [ "integer", "null" ], "description": "The CA's order number, for reference" }, "status": { "type": "object", "description": "code and description carry the same value, the state as in getCertificateStatus. While a cancellation or a reissue is pending the code has a suffix, for example issued_pending_cancel or issued_pending_reissuing.", "properties": { "code": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } } }, "name": { "type": "string", "description": "Product name" }, "domain_name": { "type": [ "string", "null" ], "description": "The common name" }, "domain_names": { "type": [ "array", "null" ], "description": "The additional domains", "items": { "type": "string" } }, "duration_in_years": { "type": [ "integer", "null" ] }, "public_comment": { "type": [ "string", "null" ] }, "valid_from": { "type": [ "string", "null" ], "description": "Start of the validity period of the current certificate" }, "valid_to": { "type": [ "string", "null" ], "description": "End of the validity period of the current certificate" }, "subscription_duration": { "type": [ "integer", "null" ], "description": "Length of the subscription in days for Sectigo multi-year subscriptions, otherwise null" }, "subscription_valid_from": { "type": [ "string", "null" ] }, "subscription_valid_to": { "type": [ "string", "null" ], "description": "End of the subscription" }, "paid": { "type": [ "boolean", "null" ], "description": "true if the certificate has been paid; false or null if not" }, "price": { "type": [ "string", "null" ], "description": "Price of the certificate, a decimal as a string" }, "currency": { "type": [ "string", "null" ] }, "token": { "type": [ "string", "null" ], "description": "Reference token of the order" }, "prolongation_token": { "type": [ "string", "null" ], "description": "Token of the renewal order, if one has been prepared; see createRenewalOrder, also for how to treat the token" }, "prolonged_id": { "type": [ "integer", "null" ], "description": "ID of the certificate this one renews (the previous certificate), or null" }, "prolonged": { "type": "boolean", "description": "Whether this certificate is a renewal (prolonged_id is set)" }, "symantec_reissue": { "type": "boolean", "description": "Internal flag" }, "dcv_method": { "type": [ "string", "null" ], "description": "The current DCV method" }, "dcv_content": { "type": [ "string", "null" ], "description": "For file-based DCV methods, the file content to publish; for a DNS_TXT_TOKEN order, the value of the TXT record" }, "all_validation_emails": { "type": [ "array", "null" ], "items": { "type": "string" } }, "all_domains": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "DcvEmails": { "type": "object", "description": "Each address group is an empty array, null, or an array of email addresses; random_value is a string", "properties": { "whois": { "type": [ "array", "null" ], "items": { "type": "string" } }, "level_2": { "type": [ "array", "null" ], "items": { "type": "string" } }, "level_3": { "type": [ "array", "null" ], "items": { "type": "string" } }, "random_value": { "type": [ "string", "null" ], "description": "The value of the DNS TXT record (DNS_TXT_TOKEN), where the certificate authority has issued one. For Sectigo it is present only for a domain whose dcv_method is DNS_TXT_TOKEN; create the record at `_pki-validation.` (for a wildcard, without the \"*.\"). The same record at _pki-validation of a parent domain also validates its subdomains." } } }, "DcvStatus": { "type": "object", "properties": { "dcv": { "type": "object", "description": "One entry per domain of the certificate. For Sectigo certificates a unique_value key can also be present at this level.", "properties": { "unique_value": { "type": [ "string", "null" ] } }, "additionalProperties": { "$ref": "#/components/schemas/DcvDomain" } } } }, "DcvDomain": { "type": "object", "properties": { "sent": { "type": [ "boolean", "null" ], "description": "Whether the DCV email has been sent (or the alternative DCV method has been started)" }, "valid": { "type": [ "boolean", "null" ], "description": "True once the domain has been validated" }, "api": { "type": [ "boolean", "null" ], "description": "True when the data comes from the CA, false for the initial local state" }, "method": { "type": [ "string", "null" ], "description": "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": { "type": [ "string", "null" ], "description": "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": { "type": [ "string", "null" ], "description": "The validation status reported by the CA" }, "emails": { "$ref": "#/components/schemas/DcvEmails" }, "hashes": { "type": "object", "description": "Sectigo only: the hashes of the CSR for the file and DNS methods. sha1 holds the SHA-256 hash despite its name.", "properties": { "md5": { "type": [ "string", "null" ] }, "sha1": { "type": [ "string", "null" ] } } }, "unique_value": { "type": [ "string", "null" ], "description": "Sectigo only: the unique value used in the request token" } } }, "Amount": { "type": "object", "properties": { "sum": { "type": "number", "description": "Rounded to 2 decimals" }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 code of the account currency" } } }, "Balance": { "type": "object", "properties": { "balance": { "$ref": "#/components/schemas/Amount", "description": "Payments received minus delivered services (acts). Includes money paid for services that are not delivered yet." }, "reserved": { "$ref": "#/components/schemas/Amount", "description": "The unpaid bills of certificates that are being issued or are already issued" }, "common": { "$ref": "#/components/schemas/Amount", "description": "balance minus reserved, the balance shown in the customer portal" }, "prepayment": { "$ref": "#/components/schemas/Amount", "description": "Paid prepayment bills that are not assigned to a service yet" }, "available": { "$ref": "#/components/schemas/Amount", "description": "Payments that are not assigned to any bill. Can be used to pay new bills." } } }, "CertificateDetails": { "type": "object", "description": "The stable fields of the getCertificate response. The response carries about 100 fields; the others (contact persons, organisation address, internal flags) may change without notice.", "properties": { "id": { "type": "integer", "description": "ID of the certificate" }, "status": { "type": "object", "description": "The state as in getCertificateStatus. Unlike that call, certificate carries the suffix of listCertificates while a cancellation or a reissue is pending, for example issued_pending_reissuing.", "properties": { "certificate": { "type": [ "string", "null" ] }, "client": { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } } } } }, "external_number": { "type": [ "string", "null" ], "description": "The CA's order number, null until the order has reached the CA" }, "common_name": { "type": [ "string", "null" ], "description": "The common name" }, "additional_domains": { "type": [ "string", "null" ], "description": "The additional domains as entered in the order, separated by commas or line breaks; use all_domains for a parsed list" }, "all_domains": { "type": "array", "items": { "type": "string" }, "description": "All domain names of the certificate" }, "valid_from": { "type": [ "string", "null" ], "description": "Start of the validity period of the current certificate; null while no certificate has been issued yet" }, "valid_to": { "type": [ "string", "null" ], "description": "End of the validity period of the current certificate; null while no certificate has been issued yet" }, "subscription_duration": { "type": [ "integer", "null" ], "description": "Length of the subscription in days for Sectigo multi-year subscriptions, otherwise null" }, "subscription_valid_from": { "type": [ "string", "null" ], "description": "Start of the subscription" }, "subscription_valid_to": { "type": [ "string", "null" ], "description": "End of the subscription" }, "replacement_id": { "type": [ "integer", "null" ], "description": "ID of the latest replacement after a reissue that created a new ID (reissueCertificate), otherwise null" }, "prolonged_id": { "type": [ "integer", "null" ], "description": "ID of the certificate this one renews (the previous certificate), otherwise null" }, "dcv_method": { "type": [ "string", "null" ], "description": "The current DCV method: EMAIL, HTTP_CSR_HASH, HTTPS_CSR_HASH, CNAME_CSR_HASH or DNS_TXT_TOKEN" }, "dcv_content": { "type": [ "string", "null" ], "description": "For file-based methods, the file content to publish; for a DNS_TXT_TOKEN order, the value of the TXT record" }, "validation_email": { "type": [ "string", "null" ], "description": "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": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "description": "The validation email address of each additional domain" }, "csr": { "type": [ "string", "null" ], "description": "The Certificate Signing Request of the current certificate, PEM" }, "nomenclature_id": { "type": [ "integer", "null" ], "description": "ID of the product, as in listProducts" }, "name": { "type": [ "string", "null" ], "description": "Name of the product in the language of your account" }, "price": { "type": [ "number", "null" ], "description": "The amount due for the certificate. Unlike price in listCertificates this amount includes VAT when VAT applies to your account; null when no price is known" }, "price_includes_vat": { "type": "boolean", "description": "Whether price includes VAT" }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 code of the price" }, "payment_status": { "type": "string", "enum": [ "paid", "unpaid", "not_payable" ], "description": "not_payable: no price, or a cancelled order" }, "unpaid": { "type": "boolean", "description": "True while the certificate is billed and the bill is not paid" } } } } } }