The API functions use authorization keys, but we use them to manage access control. It means clients can generate their own, or receive a new API key on the fly from the KeyChest server.

It means you don’t need to do any personalization for new clients and integrations can be built into the images, dockers you use to spawn new virtual machines or into simple wrappers for Let’s Encrypt clients.

What does this integration give you? There are several advantages:

1. We link all API keys and your clients via an email address they provide; which means you can see expirations, configuration problems, and so on in one view in the KeyChest web interface.
2. You can start using a new email address without registering an account – we treat such email addresses as unverified, which means we only start monitoring your servers, if we detect a relevant certificate shortly after it’s been enrolled via our API.
3. You get monitoring data from “user’s point of view”, i.e., whether their browsers will verify your servers as secure. This provides a real end-to-end validation of your server, ISP, and network configuration.

The API Logic

There are three types of calls, and three steps, you need to implement for full integration:

• Step 1: Claim API key – one-off call, where your client requests its own unique API key (we need to make sure this API key is unique). There are two versions – POST and GET. The difference is whether the client generates its own API key (POST) or KeyChest creates one and sends it back.
• Step 2: Add server – submit a domain name for monitoring.
• Step 3: Check expiration – check whether a certificate needs to be renewed. This is an optional call, which provides your code with data for e.g., triggering certbot renewal.

We recommend the client keeps two pieces of information as its state. The first item is its API key. The second is a timestamp of its last execution, which can be compared against “last scan” timestamps returned by the “Check expiration” API call.

If you’re interested in more details, please have a look further down, or at our online documentation: https://api.enigmabridge.com/api

Examples using curl

Step 1: get an API key

curl https://keychest.net/api/v1.0/access/claim/[email protected]

If you are familiar with jq, you can get a new API key with the following command:

curl -s https://keychest.net/api/v1.0/access/claim/[email protected] | jq -r '.api_key'

Step 2: register for monitoring

curl -s -X POST -H "Content-Type: application/json" -d '{"api_key":"5b9b6aceb95011e7bb9f7fca73a26228", "domain":"fish.enigmabridge.com"}' https://keychest.net/api/v1.0/servers/add

Step 3: check expiration

curl -s https://keychest.net/api/v1.0/servers/expiration/fish.enigmabridge.com?api_key=da70d5e4864f57e910e66bd21c685b26

List of basic API functions

{
    "status": "created",
    "user": "[email protected]",
    "api_key": "5b9b6aceb95011e7bb9f7fca73a26228"
}

{
    "email":"[email protected]",
    "api_key":"5b9b6aceb95011e7bb9f7fca73a26228"
}

{
    "status": "created",
    "user": "[email protected]",
    "api_key": "5b9b6aceb95011e7bb9f7fca73a26228"
}

{
    "status":"success"
}

{
    "api_key":"5b9b6aceb95011e7bb9f7fca73a26228",
    "domain":"fish.enigmabridge.com"
}

{
    "status": "success",
    "id": "671d1b10-bb1d-11e7-bae1-571d93cf1c53",
    "key": "da70d5e4864f57e910e66bd21c685b26",
    "domain": "fish.enigmabridge.com
}

{
    "domain": "fish.enigmabridge.com",
    "certificate_found":true,
    "renewal_due":true,
    "expired_found":false,
    "results": [
        {
            "ip": "2001:41c9:1:41d::131",
            "certificate_found": false,
            "certificate_sha256": null,
            "renewal_due": null,
            "expired": null,
            "renewal_utc": null,
            "last_scan_utc": 1509094412
        },
        {
            "ip": "46.43.0.131",
            "certificate_found": true,
            "certificate_sha256": "1aa7cda60ba61810321bedc4793fadc80f7ca6a3e328d484b0d5eb8a9ef230de",
            "renewal_due": true,
            "expired": false,
            "renewal_utc": 1510216500,
            "last_scan_utc": 1509099907
        }
    ],
    "status": "success"
}

If you have difficulties or encounter unexpected errors, please let us know at [email protected].