Manual work with API using the Postman tool

If you don't want to integrate our APIs into existing processes, or you have nowhere to integrate them, this guide for sending API requests using Postman will help. Thanks to this, you have a ready environment for sending queries and pre-configured functions. You can use the SSLmarket API to save your time with no programming knowledge.

Integrating the SSLmarket API into other environments has the advantage that you can implement the solution comprehensively. The solution described in the instructions can never work automatically, it is manual, but at least it will save you time.

Installing the Postman application

Download the version for your desktop on the web. Postman also exists as a web version, but it is not suitable for our purpose (it does not work).

The Windows version is installed in the traditional way, in Linux you will probably have Postman available as a snap package. In the terminal, enter:

sudo snap install postman
Then run the program. When launched, it will ask you to log in or create a user account. However, this can be skipped thanks to an inconspicuous link at the very bottom of the window. Logging in to a Postman account has the advantage of synchronizing projects between instances. You can easily continue your work at home. If you don't want to take advantage of the account and sync, or you're just testing, you don't need to sign in.

Application settings for SSLmarket

To simplify your work with the API and program as much as possible, we have prepared a "collection" of calls in the JSON file, which you simply import and all the functions are immediately available to you. Import the collection (button "import" at the top left), then select the JSON file prepared by us. In Collections, you will see the SSLmarket item and ten functions. Right-click on the SSLmarket collection and set the variables in "Edit → Variables".

editation of variables
Editation of variables for Collection. Click to enlarge.

The most important thing is to set the X-Auth-Token variable with the value from your customer account. You will certainly logically connect the other variables with the correct values, but you will find an overview of them below.

Explanation of the fields

  • X-Auth-Token – field for entering the API key
  • owner_### - details of the future owner of the certificate for specification.
  • auth_### - details of the authorization contact who confirms the order for certificates with verification.
  • tech_### - technical contact details. Technical contact persons do not enter the verification, but receive the issued certificate by email.
  • invoice_### - field for specifying invoicing data; this information defines the customer on the invoice.
set variables
Set variables for Collection. Click to enlarge.

These default data will be offered in variables (for example, when placing an order) and you will not have to enter them again. If any of the fields are not clear to you, you can find them in the API documentation.

After completing the setup and providing all the information, you can start sending requests to the SSLmarket API.

Sending a request

After setting up the program, you can start sending requests, especially new orders. The CSR must have no gaps or breaks, these must be solved using an escape sequence. More in the next paragraph.

Select the API function you want to use in the collection. Then in the right (large) part of the window in the Body tab, you will see the query construction. For example, when placing an order, all the information about the future certificate is there (the scope corresponds to the order on the website). The information in parentheses means that the variable you defined earlier will be used - for example, {{owner_name}}. You only edit these items if you need to use non-default data.

Data for placing an order

The applicant and contact details will be retrieved from the prepared default data. The following specific data needs to be specified for each order:

  • domain - Common name of the certificate
  • dns_names - list of SANs in the certificate
  • years - number of years of order validity (certificate validity is limited, but the order can be placed for more years)
  • csr - enter CSR here (must be without line spacing and spaces, see below). This is optional and you can enter the CSR directly into the SSLmarket administration even after placing the order via the API.
  • dv_auth_method - choice of DCV authentication method (email, dns, ftp)

When all the data is filled in and the request is ready, send it to the API by clicking the blue Send button.

You can see the progress and result of the query at the bottom of the window. If the result is successful, you will get the required information or order number back if you placed the order. Otherwise, you will get an error message back which specifies what is wrong or what is missing in the query.

An example of a successful order entry:

{
    "order_id": "155252"
}

An example of an error message:

   {
    "error": [
        "dv_auth_method => isEmpty - Item is required and cannot be empty"
    ]
}

Possible collisions when sending orders

  • URL used – use an endpoint URL in the form www.sslmarket.tld, not just sslmarket.tld. Otherwise, the redirection on the base domain will lead to issues with requests.
  • CSR request - Make sure that CSR is not split into multiple lines. If you have problems inserting the CSR in the correct form, then send the order without it and insert it in the standard way via administration.
    • It is not possible to send a CSR divided into lines, even if you get it from your server this way.
    • There must be no spaces, line breaks or paragraph breaks in the CSR; end the lines with "escape sequences" rn.
    • You can easily adjust the CSR to the appropriate format with one click using the Remove or replace line breaks tool. Select the "Replace line breaks with customer text" option and enter rn as the custom text. Clear the other options and click the green button below.

FAQ for manual use of API

Not from the point of view of the available functions - both approaches bear the same results. Using the SSLmarket API with Postman will save you the time and expense of integrating the API into another system, but you need to run the actions manually, which is the only disadvantage of this approach. You cannot automate the ordering or renewal of certificates, you need your own solution with our API’s implementation.

You will find all orders in your customer account, the same as you would enter them in the traditional way via the web. Your request identifies the generated API key for the correct account.