API

Getting Started

To get started with the Tenant SSL API, you’ll need your:

  • API Login
  • API Password

Both of these are obtainable in your account dashboard. Each account has its own API Login. You can generate as many API Passwords as you need by clicking on Generate API Password.

Endpoint

The endpoint is located at https://app.tenantssl.com/api.

Authentication

Each request that is made to the API needs to be authenticated. Authentication is passed through with the following request headers:

  • X-Api-Login
  • X-Api-Password

The values of these headers correspond to the API Login and API Password values that you obtained from above.

Here’s an example API call using curl:

curl -H "X-API-Login=f123jkjd9s0jf12" -H "X-API-Password=j123ljdf-021df-123kldf" https://api.tenantssl.com/api/domains

Format

Both request and response must be in JSON format. If you see the [id] parameter in the URL, replace it with the ID of the Domain object that’s provided when you created a new Domain object via the API.

With each request below, Tenant SSL will return the domain object in JSON format.

To make it consistent across each request and to make it easy for your web application to process the object that returns, the domain object is returned with every request.

For example, if you post a GET to /api/domains, Tenant SSL will return an array of the Domain object. If you send a DELETE request to /api/domains/[id], Tenant SSL will return the domain object you just deleted.

Here’s what the JSON object looks like for the Domain object:

{
  id: 1,
  name: "mydomain.com",
  created_at: "2018-06-03 03:52:53 UTC",
  updated_at: "2018-06-03 
03:52:53 UTC",
  status: "pending",
expired: true,
issued: false,
errors: [] }

id: The unique ID for the domain

name: The domain name itself

created_at: The UTC timestamp when the record was created.

updated_at: The UTC timestamp when the record was updated.

status: The validity status with Let’s Encrypt. Either pending/invalid/valid.

expired: Returns whether the SSL certificate is expired. Either true/false. For new records, this returns false as well. 

issued: The UTC timestamp when the record’s SSL certificate was issued. Returns null if it has never been issued.

errors: Returns an array of error messages related to the record when creating a new domain record. An empty array is returned when no errors are found.

Retrieves all domains under the specific account. Returns an array of Domain objects.

Returns a single domain with the specified ID. Returns a single domain object.

Create a new domain. Returns object that was created. If the creation of the object was not successful, it will return the object still but with the additional property of “errors”, which itself is an array.

Sending a POST request will also trigger the system to attempt domain validation with Let’s Encrypt and issue a SSL certificate. If the custom domain isn’t already pointing to your infrastructure, the validation will fail (and no certificate will be issued). You can retrieve the status of a custom domain at any time by sending a GET request to the /api/domains/[id] endpoint.

Note: In order to prevent rate limiting by Let’s Encrypt, Tenant SSL will only attempt a single verification and will not requeue for verification should it fail. In order to verify the domain again, call the /api/domains/[id]/verify.json endpoint.

Deletes and removes domain. Returns the domain object that was just deleted. Future requests to this Domain object (eg. through a GET request at /api/domains/[id]) will return a 400 level error.

Manually queue Tenant SSL to verify the domain and issue SSL certificate. If a domain verification was previously attempted and the domain was deemed “invalid”, the status of the Domain object will change to “pending” once you call this resource.