How to use the Qloaked API

Introduction

The API can be used to query the status of domains within Qloaked. This allows you to determine if a domain has been correctly configured, and whether a SSL certificate has been issued for the domain.

You will need an API Key to use the API which you can setup here: https://app.qloaked.com/api

Making requests to the API

Provide the following headers, replacing API_KEY_VALUE with your API key.

Content-Type: application/javascript
X-Api-Key: API\_KEY\_VALUE

Querying the domains

Qloaked provides a simple versioned rest interface:

GET /v1/domains - Returns a paginated list of domains
POST /v1/domains - Create a new domain (See more details below)
GET /v1/domains/{fqdn} - Returns the data for the Fully Qualified Domain Name (fqdn)
PUT /v1/domains/{fqdn} - Set thed domain to enabled or disabled
DELETE /v1/domains/{fqdn} - Delete the domain

Create a new domain

1. The domain should be configured to point at your application CNAME e.g. secured.yourcompany.com

2. Pass in the following body, replacing DOMAIN_NAME_VALUE with the FQDN without any protocol e.g. www.qloaked.com and not https://www.qloaked.com

 { "domainName": "DOMAIN\_NAME\_VALUE"}

Response

If the request was successful, the response will be a 200:

{ "id": DOMAIN\_ID, status: "STATUS\_CODE" }

pending-certificate - The domain is configured correctly but a certificate has not yet been issued.

ready - The domain is ready for use.

Once the domain is in the pending-certificate state, users can visit the domain in their browser to trigger the procurement of a certificate. The Qloaked API will also attempt to trigger the procurement of a certificate but this process will happen after the API request is made.

Response errors

For failed requests you will get different HTTP responses based on the problem encountered:

*   500 - { success: false, error: "DNS lookup failed" }
*   400 - { success: false, error: "DNS not configured correctly for domain" }
*   404 - { success: false, error: "Application lookup failed"}
*   401 - { success: false, error: "Application for this key invalid"}
*   500 - { success: false, error: "Domain update failed"}

The 500 errors are problems with Qloaked and you can contact our support team to help you resolve them.

Enable/Disable a domain

You can enable and disable a domain using the following request

PUT /v1/domains/{fqdn} - Set the domain to enabled or disabled and a JSON body like below

{ "enabled": false}

When a domain is disabled you will no longer be charged for it and visitors will hit a disabled page instead of being routed to your application.

What's the difference between disabling a domain vs deleting a domain?

When a domain is disabled it will still be in your account but when someone visits it they will see a domain is disabled message.

When someone visits a domain which has been deleted but is still pointing at your application we will re-provision the SSL again and send it on to your application.

We recommend if it's an unknown domain or someone you want to block for security/spam reasons, you disable the domain.

If it's a customer that has unsubscribed but may come back in the future you should delete their domain and we will detect and re-provision if they point their domain at your application again.

Documentation Hub