Page History

Instructions für complete automation of the certificate ordering process. The QuickSSLPremium product is used here as an example and DNS is used as the authentication method.

The ordering process for S/MIME certificates differs and is described separately.

Panel

titleColor	#FFFFFF
titleBGColor	#E44313
title	Table of Contents

Table of Contents

outline	true
style	none

Basics of the JSON and XML API

All important information for the use of the JSON and XML API can be found under the following links:

JSON API General Information and further articles
SSL XML API

Process Overview

Flow Chart

Tasks Names, Codes and Routes

CertificateCreate400101certificate

Task	Code	Route
CertificatePrepareOrder	400110	POST /certiicate/prepareOrder
ContactCreate	400201	POST /	sslcontact
ContactCreateCertificateCreate	400201400101	POST /sslcontactcertificate
PollInfo	0905	GET /poll
PollConfirm	0906	PUT /poll/$id
CertificateInfo	00104	GET /certificate/$id

DNS Validation

DNS validation, i.e. validation by zone entry, is supported by many domain-validated certificates. To do this, you must store a specific TXT or CNAME record in the zone belonging to the certificate name. This is checked for validity by the issuing certificate authority. If the corresponding zone is managed by InterNetX, the provisioning of the zone takes place automatically.

Preparation

Anchor
connect
connect
Connect SSLManager to AutoDNS

For the automatic provisioning of the zone, you have to connect the SSLManager to your AutoDNS access once. In the SSL Manager go to the User Configuration and click on the menu item Connect SSL Manager to the Domain Administration System.

Info
If necessary, you habe to enter the URL to your AutoDNS yourself.

You will then be redirected to the AutoDNS login page. Enter your AutoDNS credentials here to establish the connection.

Create Contact

A technical and administrative contact is required to order a QuickSSLPremium certificate. You can use existing contacts or create new contacts. You can use the new contacts for future orders.

ContactCreate - Example

SP Tabs group

disposition	horizontal

SP Tab pane

name	JSON

Code Block

language	js
title	Request
linenumbers	true
collapse	true

POST /sslcontact
{
  "fname": "John",
  "lname": "Doe",
  "phone": "+49-123-12345",
  "fax": "+49-123-12345",
  "email": "john.doe@example.com",
  "title": "Admin",
  "organization": "Company",
  "address": "123 Main Street",
  "pcode": "12345",
  "city": "Anytown",
  "country": "DE",
  "state": "BY"
}

Code Block

language	js
title	Response
linenumbers	true
collapse	true

{
    "stid": "20180926-stid",
    "status": {
        "code": "S400201",
        "text": "Contact was created successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "contact",
        "value": "100"
    },
    "data": [
        {
            "fname": "John",
            "lname": "Doe",
            "phone": "+49-123-12345",
            "email": "john.doe@example.com",
            "title": "Admin",
            "organization": "Company",
            "address": "123 Main Street",
            "pcode": "12345",
            "city": "Anytown",
            "country": "DE",
            "state": "BY",
            "owner": {
                "user": "user",
                "context": 9
            },
            "id": 100
        }
    ]
}

SP Tab pane

name	XML

Code Block

language	xml
title	Request
linenumbers	true
collapse	true

<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400201</code>
        <contact>
            <first>Michael</first>
            <last>Mustermann</last>
            <phone>+49-941-1234560</phone>
            <email>michael.mustermann@example.com</email>
            <title>Admin</title>
            <organization>Beispiel GmbH</organization>
            <address>Maximilianstrasse 36000</address>
            <postal_code>93047</postal_code>
            <city>Regensburg</city>
            <country>DE</country>
            <state>Bayern</state>
        </contact>
    </task>
</request>

Code Block

language	xml
title	Response
linenumbers	true
collapse	true

<response>
    <result>
        <data/>
        <status>
            <code>S400201</code>
            <text>Contact was created successfully.</text>
            <type>success</type>
            <object>
                <type>contact</type>
                <value>100</value> <!-- The ID of the created contact -->
            </object>
        </status>
    </result>
</response>

Order a QuickSSLPremium Certificate

Create DNS Record and check CSR

QuickSSLPremium certificates are verified by TXT entries. A new TXT record with specific values must be stored in the zone belonging to the common name (CNAME). With the CertificatePrepareOrder task, the CSR key provided is checked for the correct bit length, for example, and the required authentication data is generated.

Example TXT : 
example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"

CertificatePrepareOrder - Example

SP Tabs group

disposition	horizontal

SP Tab pane

name	JSON

Code Block

language	js
title	Request
linenumbers	true
collapse	true

POST /certificate/prepareOrder
{
  "plain": "----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----",
  "product": "QUICKSSLPREMIUM"
}

Code Block

language	js
title	Response
linenumbers	true
collapse	true

{
    "stid": "20180926-stid",
    "status": {
        "code": "S400110",
        "text": "CSR key was checked successfully.",
        "type": "SUCCESS"
    },
    "data": [
        {
            "plain": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
            "name": "example.com",
            "keySize": 2048,
            "countryCode": "DE",
            "state": "BY",
            "city": "Regensburg",
            "organization": "Company GmbH",
            "organizationUnit": "Entwicklung",
            "product": "QUICKSSLPREMIUM",
            "authentication": [
                {
                    "method": "EMAIL",
                    "approverEmails": [
                        "admin@example.com",
                        "administrator@example.com",
                        "hostmaster@example.com",
                        "webmaster@example.com",
                        "postmaster@example.com"
                    ]
                },
                {
                    "method": "DNS",
                    "dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\""
                },
                {
                    "method": "FILE"
                }
            ],
            "algorithm": "RSA",
            "signatureHashAlgorithm": "SHA256"
        }
    ]
}

SP Tab pane

name	XML

Code Block

language	xml
title	Request
linenumbers	true
collapse	true

<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400110</code>
        <certificate_request>
            <plain><![CDATA[----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></plain>
            <product>QUICKSSLPREMIUM</product>
        </certificate_request>
    </task>
</request>

Code Block

language	xml
title	Response
linenumbers	true
collapse	true

<response>
    <result>
        <data>
            <certificate_request>
                <plain><![CDATA[-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----]]></plain>
                <name><![CDATA[example.com]]></name>
                <key_size>2048</key_size>
                <country_code>DE</country_code>
                <state><![CDATA[Bayern]]></state>
                <city><![CDATA[Regensburg]]></city>
                <organization><![CDATA[Company GmbH]]></organization>
                <organization_unit>Entwicklung</organization_unit>
                <email>email@example.com</email>
                <product>QUICKSSLPREMIUM</product>
                <authentication>
                    <method>DNS</method>
                    <dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
     				<provisioning>1</provisioning>
                </authentication>
                <authentication>
                    <method>FILE</method>
                    <file_name><![CDATA[http://example.com/.well-known/pki-validation/fileauth.txt]]></file_name>
                    <file_content><![CDATA[201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q]]></file_content>
                </authentication>
                <algorithm>RSA</algorithm>
                <signature_hash_algorithm>SHA256</signature_hash_algorithm>
            </certificate_request>
        </data>
        <status>
            <code>S400110</code>
            <text>CSR key was checked successfully.</text>
            <type>success</type>
        </status>
    </result>
</response>

Certificate Create

With the order type CertificateCreate you send the actual order to the system. You must set certain values:

Contact: Enter the contact ID of the required contacts. For QuickSSLPremium these are the administrative and the technical contact.
Name: The name of the certificate.
Product: The value for QuickSSLPremium is QUICKSSLPREMIUM
Authentication: The generated authentication data
Term: Specify a term allowed for the certificate. For QuickSSLPremium, this is 12 or 24 months.
Software: select APACHESSL or IIS5
CSR: The CSR that is part of the certificate

Info
For the automatic provisioning of the zone, i.e. the automatic triggering of the zone update, it must be managed via AutoDNS and the SSL Manager and AutoDNS systems must be linked. See step Connect SSLManager to AutoDNS

CertificateCreate - Example

SP Tabs group

disposition	horizontal

SP Tab pane

name	JSON

Code Block

language	js
title	Request
linenumbers	true
collapse	true

POST /certificate
{
  "adminContact": {
    "id": 100
  },
  "technicalContact": {
    "id": 100
  },
  "name": "example.com",
  "lifetime": {
    "unit": "MONTH",
    "period": 12
  },
  "software": "APACHESSL",
  "csr": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
  "product": "QUICKSSLPREMIUM",
  "authentication": {
    "method": "DNS",
    "dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\"",
    "provisioning": true
  }
}

Code Block

language	js
title	Response
linenumbers	true
collapse	true

{
    "stid": "20180926-stid",
    "status": {
        "code": "N400101",
        "text": "Certificate order was started successfully.",
        "type": "NOTIFY"
    },
    "object": {
        "type": "certificate",
        "value": "example.com"
    },
    "data": [
        {
            "id": 123456
        }
    ]
}

SP Tab pane

name	XML

Code Block

language	xml
title	Request
linenumbers	true
collapse	true

<request>
    <auth>
        <user>USER</user>
        <password>PASSWORD</password>
        <context>CONTEXT</context>
    </auth>
    <task>
        <code>400101</code>
        <certificate>
            <technical>
                <id>100</id>
            </technical>
            <admin>
                <id>100</id>
            </admin> 
            <name>example.com</name>
            <product>QUICKSSLPREMIUM</product>
            <authentication>
                <method>DNS</method>
                <dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns> 
                <provisioning>1</provisioning>
            </authentication>
            <lifetime>12</lifetime>
            <software>APACHESSL</software> <!-- APACHESSL / IIS5 -->
            <csr><![CDATA[---------BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></csr> <!-- Der CSR KEY -->
        </certificate>
    </task>
</request>

Code Block

language	xml
title	Response
linenumbers	true
collapse	true

<response>
  <result>
    <data>
      <certificate_job>
        <job>
          <id>123456</id>
          <status>RUNNING</status>
        </job>
      </certificate_job>
    </data>
    <status>
      <code>N400101</code>
      <text>Certificate order was started successfully.</text>
      <type>notify</type>
      <object>
        <type>certificate</type>
        <value>example.com</value>
      </object>
    </status>
  </result>
</response>

Checking and Confirming Notifications

The CertificateCreate task automatically generates a request for ordering the certificate. Once the request has been processed, a request notification is generated with information about the request. You can query this using the order type PollInfo. If the order was successful, you receive, among other things, the ID of the certificate ordered. Finally you have to confirm the order with PollConfirm.

PollInfo - Examples

SP Tabs group

disposition	horizontal

SP Tab pane

name	JSON

Code Block

language	js
title	Request
linenumbers	true
collapse	true

GET /poll

Code Block

language	js
title	Response
linenumbers	true
collapse	true

{
    "stid": "20180926-stid",
    "status": {
        "code": "S0905",
        "text": "The notification was polled successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1405448",
        "summary": 2
    },
    "data": [
        {
            "id": 1405448,
            "job": {
                "created": "2018-12-11T15:10:43.000+0100",
                "updated": "2018-12-11T15:10:55.000+0100",
                "status": "SUCCESS",
                "execution": "2018-12-11T15:10:42.000+0100",
                "id": 9218718,
                "type": "ssl",
                "subType": "QUICKSSLPREMIUM",
                "action": "create"
            },
            "stid": "20180926-stid",
            "object": {
                "type": "Certificate",
                "value": "example.com",
                "data": {
                    "created": "2018-12-11T00:00:00.000+0100",
                    "id": 570,
                    "orderId": "2742528",
             ...
                }
            }
        }
    ]
}

SP Tab pane

name	XML

Code Block

language	xml
title	Request
linenumbers	true
collapse	true

<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>0905</code>
    </task>
</request>

Code Block

language	xml
title	Response
linenumbers	true
collapse	true

<response>
    <result>
        <data>
            <summary>1</summary>
            <message>
                <id>1855680</id>
                <owner>
                    <user>alex_normal_plus</user>
                    <context>4</context>
                </owner>
                <job>
                    <domain>
                        <name>example.com</name>
                        <expire>2019-10-15 14:02:40</expire>
                        <payable>2019-10-15 14:02:41</payable>
                        <ownerc>100</ownerc>
                        <adminc>100</adminc>
                        <techc>100</techc>
                        <nic_member_label>VGRS-TEST</nic_member_label>
                        <registry_status>LOCK</registry_status>
                        <nserver>
                            <name>a.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>b.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>c.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>d.ns14.net</name>
                        </nserver>
                        <period>1</period>
                        <authinfo>S0Lygv+ZkNbniICm</authinfo>
                        <autorenew>true</autorenew>
                        <confirm_order>1</confirm_order>
                        <confirm_owner_consent>0</confirm_owner_consent>
                        <registrar_status>ACTIVE</registrar_status>
                        <rdds_opt_in>NOT_SET</rdds_opt_in>
                        <owner/>
                        <updater/>
                        <created>2018-10-15 14:02:41</created>
                    </domain>
                    <job_id>4295625406</job_id>
                    <status>
                        <code>S0101</code>
                        <type>success</type>
                        <object>
                            <type>domain</type>
                            <value>example.com</value>
                        </object>
                    </status>
                    <stid>20181015-app1-3788</stid>
                </job>
                <created>2018-10-15 14:03:02</created>
            </message>
        </data>
        <status>
            <code>S0905</code>
            <text>The notification was polled successfully.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>1855680</value>
            </object>
        </status>
    </result>
    <stid>20181015-app1-3805</stid>
</response>

PollConfirm - Examples

SP Tabs group

disposition	horizontal

SP Tab pane

name	JSON

Code Block

language	js
title	Request
linenumbers	true
collapse	true

PUT /poll/{id}

Code Block

language	js
title	Response
linenumbers	true
collapse	true

{
    "stid": "20180926-stid",
    "status": {
        "code": "S0906",
        "text": "The notification was confirmed successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1819853"
    }
}

SP Tab pane

name	XML

Code Block

language	xml
title	Request
linenumbers	true
collapse	true

<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>0906</code>
       <message>
            <id>650664</id>
        </message>
    </task>
</request>

Code Block

language	xml
title	Response
linenumbers	true
collapse	true

<response>
    <result>
        <data>
            <summary>0</summary>
            <message>
                <id>650664</id>
            </message>
        </data>
        <status>
            <code>S0906</code>
            <text>The notification was confirmed successfully.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>650664</value>
            </object>
        </status>
         <stid>20181015-app1-3162</stid>
	 </result>
</response>

Inquire Certificate Data

The CertificateInfo task inquires the certificate data. The data can be queried and confirmed using the ID from the Checking and Confirming Notificationsstep.

Certifica tInfo - Example

SP Tabs group

disposition	horizontal

SP Tab pane

name	JSON

Code Block

language	js
title	CertificateInfo Request
linenumbers	true
collapse	true

GET /certificate/$id

Code Block

language	js
title	CertificateInfo Response
linenumbers	true
collapse	true

{
    "stid": "20180926-stid",
    "status": {
        "code": "S400104",
        "text": "Certificate data were inquired successfully..",
        "type": "SUCCESS"
    },
    "object": {
        "type": "certificate",
        "value": "example.com"
    },
    "data": [
        {
            "created": "2018-09-26T00:00:00.000+0200",
            "updated": "2018-09-26T11:38:08.000+0200",
            "id": 13258,
            "owner": {
                "user": "user",
                "context": 9
            },
            "orderId": "2695961",
            "adminContact": {
                "id": 100
				...
            },
            "technicalContact": {
                "id": 100
				...
            },
            "name": "example.com",
            "lifetime": {
                "unit": "MONTH",
                "period": 12
            },
            "software": "APACHESSL",
            "csr": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----",
            "server": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----\n",
            "serialNumber": "750C3006B23B90D0F396A3D153EB4C8",
            "product": "QUICKSSLPREMIUM",
            "expire": "2019-09-26T12:00:00.000+0200",
            "authentication": {
                "method": "DNS",
                "dns": "example.com.\t\t300\tIN\tTXT\t\"2018092608362142n4sbul8rv8ttv7zkhjgzvyim8n1kpa9lys0uqdszxzs0pa0l\"",
                "provisioning": true
            },
            "certificateTransparencyPrivacy": "PUBLIC",
            "domain": "example.com"
        }
    ]
}

SP Tab pane

name	XML

Code Block

language	xml
title	CertificateInfo Request
linenumbers	true
collapse	true

<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>400104</code>
        <certificate>
            <id>100</id>
        </certificate>
    </task>
</request>

Code Block

language	xml
title	CertificateInfo Response
linenumbers	true
collapse	true

<response>
  <result>
    <data>
      <certificate>
        <order_id>1003396954</order_id>
        <technical>
          <first>John</first>
            <last>Doe</last>
            <phone>+49-941-1234560</phone>
            <email>k.doe@example.com</email>
            <title>Admin</title>
            <organization>Example GmbH</organization>
            <address>Maximilianstrasse 36000</address>
            <postal_code>93047</postal_code>
            <city>Regensburg</city>
            <country>DE</country>
            <state>Bayern</state>
          <owner>
            <user>USER</user>
            <context>CONTEXT</context>
          </owner>
          <updater>
            <user>USER</user>
            <context>CONTEXT</context>
          </updater>
          <id>20398</id>
          <created>2017-01-01 10:35:22</created>
          <updated>2017-01-01 01:05:07</updated>
        </technical>
        <admin>
          <first>John</first>
            <last>Doe</last>
            <phone>+49-941-1234560</phone>
            <email>j.doe@example.com</email>
            <title>Admin</title>
            <organization>Example GmbH</organization>
            <address>Maximilianstrasse 36000</address>
            <postal_code>93047</postal_code>
            <city>Regensburg</city>
            <country>DE</country>
            <state>Bavaria</state>
          <owner>
            <user>USER</user>
            <context>CONTEXT</context>
          </owner>
          <updater>
            <user>USER</user>
            <context>CONTEXT</context>
          </updater>
          <id>20398</id>
          <created>2017-01-01 10:35:22</created>
          <updated>2017-01-01 01:05:07</updated>
        </admin> 
        <name>example.com</name><!-- ertificate name -->
        <lifetime>12</lifetime><!-- certificate runtime -->
        <software>APACHE2</software>
        <csr><![CDATA[----BEGIN CERTIFICATE REQUEST----- .... -----END CERTIFICATE REQUEST-----]]></csr>
        <server><![CDATA[----BEGIN CERTIFICATE ----- .... -----END CERTIFICATE-----]]></server>
        <serial_number>SERIALNUMBER</serial_number>
        <product>QUICKSSLPREMIUM</product>
        <sha>SHA2</sha>
        <expire>2030-01-01 23:59:59</expire><!-- certificate expire date -->
        <extension />
        <certification_authority>
          <ca_type>ICA1</ca_type>
          <ca_cert><![CDATA[----BEGIN CERTIFICATE ----- .... -----END CERTIFICATE-----]]></ca_cert>
        </certification_authority>
        <authentication>
          <method>DNS</method>
          <dns>example.com. 300 IN TXT "201704071405295z34is5g0jjairsdu0v5opdw8512td8kixzvtaacu4ebrkry5q"</dns>
        </authentication>
        <owner>
          <user>USER</user>
          <context>CONTEXT</context>
        </owner>
        <updater>
          <user>USER</user>
          <context>CONTEXT</context>
        </updater>
        <id>100</id><!-- certificate id -->
        <created>2017-01-01 00:00:00</created>
        <updated>2017-01-01 14:30:36</updated>
      </certificate>
    </data>
    <status>
      <code>S400104</code>
      <text>Certificate data were inquired successfully..</text>
      <type>success</type>
      <object>
        <type>certificate</type>
        <value>example.com</value><!-- certificate name -->
      </object>
    </status>
  </result>
</response>

Versions Compared

Old Version 19

New Version 20

Key

Basics of the JSON and XML API

Process Overview

Flow Chart

Tasks Names, Codes and Routes

DNS Validation

Preparation

Anchor
connect
connect
Connect SSLManager to AutoDNS

Create Contact

ContactCreate - Example

Order a QuickSSLPremium Certificate

Create DNS Record and check CSR

CertificatePrepareOrder - Example

Certificate Create

CertificateCreate - Example

Checking and Confirming Notifications

PollInfo - Examples

PollConfirm - Examples

Inquire Certificate Data

Certifica tInfo - Example

Page History

Versions Compared

Old Version 19

New Version 20

Key

Basics of the JSON and XML API

Process Overview

Flow Chart

Tasks Names, Codes and Routes

DNS Validation

Preparation

AnchorconnectconnectConnect SSLManager to AutoDNS

Create Contact

ContactCreate - Example

Order a QuickSSLPremium Certificate

Create DNS Record and check CSR

CertificatePrepareOrder - Example

Certificate Create

CertificateCreate - Example

Checking and Confirming Notifications

PollInfo - Examples

PollConfirm - Examples

Inquire Certificate Data

Certifica tInfo - Example

Anchor
connect
connect
Connect SSLManager to AutoDNS