Link Search Menu Expand Document

Introduction

The RCL Stand Alone Certificate APIs allow subscribers to the RCL Client for Let’s Encrypt application to develop custom systems and software tools for the creation, renewal and installation of ‘Stand Alone’ TLS/SSL certificates.

Concepts

Authorization

You will obtain an API Key in the RCL Let’s Encrypt admin portal to make authorized requests to the APIs.

To make an authorized request, you must include the API Key as a query string parameter in an API’s request URL. The following is an example of the use of the API Key :

https://rclapi.azure-api.net/v2/stand-alone/csrinfo?api-key=7boT43577bf5Er54ytres34

Certificate Signing Request Information (CsrInfo)

The CsrInfo contains the details of the organization creating the TLS/SSL certificate. The CsrInfo must be created before a Certificate can be created.

The CsrInfo APIs allows for the creation, retrieval and deletion of the CsrInfo in a user’s subscription.

Challenge

Completing a Challenge proves that you own the domain for which you are creating the certificate. There are two types of challenges :

  • HTTP - in the HTTP challenge, you will place an extensionless file with a specific token value content in a folder with a specific token name in the root of your website. To validate the website domain, a GET request is sent to the extenionless file in your website and the validator checks for the correct token value in the content.

  • DNS - in the DNS challenge, you will create a DNS TXT record with a specific token name as its name and a specific token value as the record’s value. The DNS TXT record is created in the Management Portal of your DNS provider (eg. GoDaddy, DNSimple, etc.). To validate the website domain, a DNS search is used to look for the DNS TXT record and the validator will check for the correct DNT TXT record value.

You will use the API to create a Challenge and in the API’s response the token name and token value will be returned. You can then use to token name and value to complete the challenge using the HTTP or DNS method.

After you have completed the challenge, you can then proceed to create the certificate.

Certificate

After you have created the CsrInfo and created a Challenge, you can then create a TLS/SSL certificate.

When you create a Challenge using the API, a CertificateOrder object is returned within the Challenge object the response. This CertificateOrder will contain an orderUri property. This URI is used to validate the challenge and create the certificate.

You must successfully complete the challenge by using the HTTP or DNS method to ensure the validations will pass.

After you complete the HTTP or DNS challenge, you will post the CertificateOrder to the Certificate API to start the validation process and to create the certificate.

You can also use the Certificate API to list all the certificates or delete a specific certificate in your subscription.

Quick Start - Create a TLS/SSL Certificate

Follow the steps in this Quick Start to quickly create and a TLS/SSL certificate using the APIs.

1. Authorization

  • Create and API Key to call the APIs

2. CsrInfo

  • Create a CsrInfo in your subscription

3. Challenge

  • Create a Challenge for your TLS/SSL certificate

  • Use the ‘tokenValue’ and ‘tokenName’ to complete the Challenge using the HTTP or DNS method

  • Copy the CertificateOrder object within the Challenge object returned when you created the challenge. We will use it in step 4.

4. Certificate

  • Ensure you complete the Challenge in step 3 using the HTTP or DNS method before you proceed with the next steps

  • Post the CertificateOrder object that you obtained in step 3 to Create a Certificate

  • In the response, use the download links to download the certificate files

Advanced Usage

You can use the APIs to create sophisticated systems and software tools to :

  • Automatically create TLS/SSL certificates
  • Automatically renew certificates before they expire
  • Automatically install certificates in web servers or website hosting providers