API Overview

The SSL Store’s REST API works perfectly over HTTP Protocol. Generally speaking, an API on REST has the following components:

  1. URL – A url suggests the action that you want to take over a specific resource
  2. HTTP VERBS – GET, POST, PUT, DELETE, etc. – Usually indicates the operation you want to perform over a specific resource.
  3. PARAMETERS – Whether it is in GET or POST, it signifies the parameters that need to be passed as arguments over the action you wish to take.
  4. RESPONSE – Indicates the response that you can expect after performing a specific action over a specific resource with said collection of parameters.

TheSSLStore.com provides 2 URLs for interfacing with it. One for the SANDBOX API, which returns dummy products and the other, is for the LIVE API which actually interacts with your live API.

SANDBOX URL :

https://sandbox-wbapi.thesslstore.com/rest/

LIVE URL :

https://api.thesslstore.com/rest/

If you do not have a Sandbox Environment PartnerCode and Auth Token, please send an e-mail to request one.

Note: Although we do not offer a European Sandbox URL, we do offer a Live European URL for those who wish to use it at https://api.thesslstore.eu/rest/. The same REST methods can be used for the .com and .eu Live domains.

Common Terms:

Approver :
Applicable only for Domain Vetted Orders. The Approver is differentiated from the Requestor. The Approver is an individual who has domain control and has the responsibility for approving the Requestor’s request for a Domain Vetted product (such as QuickSSL and SSL123).

Certificate Signing Request (CSR) :
The Certificate Signing Request (CSR) is a block of information typically generated by the Web Server software that is meant to be submitted to a Certificate Authority (CA) in return for a SSL certificate. The CSR provide the Certificate Authority with the information necessary to generate the SSL Digital Certificate. When the Web Server generates the CSR it is actually generating a Private and Public Key pair. The private key is kept secret and the public key is bundled into the CSR. The CSR is digitally signed by the private key which proves to the CA that the Web Server has possession of the private key (called “proof of possession”).

Domain Vetting :
Domain vetting is the process for verifying that a Requestor has permission from an Approver to order the product. The Approver must demonstrate control of the domain. For eg : GeoTrust QuickSSL is a Domain Vetted product.

Vetting philosophy is to prove that a server legally represents its domain. What needs to be established is that the domain being ordered (either as part of a certificate request, or as a Verified Domain) is legally registered, and that the order is reviewed and approved by an individual that has administrative control over the management or use of the domain.
Because domain registrar databases are online, and since the authorized individuals established with the domain registrar are typically the same ones that would apply for a digital certificate or Verified Domain site seal, this process can be completely automated.

Here is how general Domain Vetting process works :

  1. The user enters their Certificate Signing Request (CSR) or requested domain, contact information, and billing information into the enrollment form.
  2. The user then selects the individual to approve this order. The list of possible email addresses is computed dynamically based on the domain name. This list of email addresses contains the registered domain administrator and technical contacts as registered with the Registrar (if available). The user can also select from one of the other standard administrative email addresses like [email protected] or [email protected]. This works on the theory that more than 95% of the time this is the individual that is requesting the certificate, or is “in the loop” with this request process and can approve the order in a timely manner. The third option is to select a Manual approval method which results in a GeoTrust individual determining the appropriate email address on behalf of the requestor. When this option there will be a delay in fulfilling the order.
  3. The system validates the data and sends out the approval email message to the specified individual. Typically, the individual enrolling receives the email immediately upon submission of the order.
  4. When the approver receives the email, they can view the special URL that allows them to come to the order approval site to approve the order. Once approved, GeoTrust immediately initiates fulfillment processing.
  5. Email notification is sent to the order contacts and to the approver (as confirmation). For certificate orders, the GeoTrust-issued certificate is included in the email

Operation :
A function within a Web Service. Synonymous with API function, or method.

Organization Vetting :

Vetting process where verification of corporate identity and ownership of the associated domain is verified as a basis for providing the product to the requestor. Examples of Organization Vetted products include True Business ID and all the Verisign products.

As part of the vetting process, some vendors may require the customer to fax their Proof of Organization information and InterNIC record to them. This must include the domain name and order ID number on the cover letter. If any of the above items do not match or are not submitted, the processing of the certificate request may be delayed.

Generally Acceptable documents for Proof of Organization include:

  1. DUNS number (Dun and Bradstreet)
  2. Articles of Incorporation
  3. Business License
  4. Doing Business As (DBA) registration
  5. Partnership documentation
  6. Sole Proprietorship documentation

Government Department, Non-Government Organization, or University, organizations will be asked to generate to provide a special letter in lieu of Proof of Organization documents.

For these two products, Organizational information must consistently match between these 3 sources :

  1. The Organization appearing in your “Proof of Organization” documents, DUNS number, or Department of state records.
  2. The Registrant listed in the InterNIC/WHOIS records for the domain name in question
  3. The Organization entered into the CSR (Certificate Signing Request) if you ordered a Organization vetted certificate.

Once a request has successfully passed the authentication process, the certificate is generated and issued to the contacts listed in the order

REST :

REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource.

The client begins sending requests when it is ready to make the transition to a new state. While one or more requests are outstanding, the client is considered to be in transition. The representation of each application state contains links that may be used next time the client chooses to initiate a new state transition.

The name “Representational State Transfer” is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through the application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use.

REST was initially described in the context of HTTP, but is not limited to that protocol. RESTful architectures can be based on other Application Layer protocols if they already provide a rich and uniform vocabulary for applications based on the transfer of meaningful representational state. RESTful applications maximize the use of the pre-existing, well-defined interface and other built-in capabilities provided by the chosen network protocol, and minimize the addition of new application-specific features on top of it.

Requestor :

Most applicable in Domain Vetted orders. The Requestor is the end user requesting the SSL certificate. This role is differentiated from the Approver. In Domain Vetted Orders the Requestor selects the approver email address from a list of authoritative email addresses.

Vetting :

The process of verifying something. For example, with the GeoTrust True Business ID product, GeoTrust “vets” the validity of the organization name.

Web Service :
A logical grouping of Operations (see definition above). A Web Service can be directly addressed via a URL endpoint.

Web Service Description Language (WSDL) :
This is the XML that describes the Web Service’s Operations, including the data for input and output. WSDL is not particularly readable by humans and is typically used by development tools to assist the developer when calling a Web Service.

For any comments/suggestions or help, please send us an e-mail. For technical samples, please visit our Getting Started section at https://www.thesslstore.com/api/getting-started