Certificates

This document describes the KraftCloud Services REST API (v1) for managing TLS certificates for custom domains.

Certificates for Custom Domains

KraftCloud allows you to host your deployment at subdomains of <metro>.kraft.host and/or use custom domains (e.g., example.com).

For subdomains, your deployment will use the wildcard TLS certificate of the respective KraftCloud metro.

For custom domains, you need a TLS certificate specifically generated for your domain. KraftCloud automatically configures the correct TLS certificate for you. To specify a custom domain, provide the fully-qualified domain name in POST /v1/instances or POST /v1/services. KraftCloud will check if any of your existing certificates applies to the domain, and if not request one using Let’s Encrypt™.

Certificate States

A certificate can be in one of the following states:

State	Description
pending	The certificate request is pending while the certificate is being requested from the certification authority. During this phase any service using this certificate is not available if this is not a renewal
valid	The certificate is valid and can be used by your services
error	The certificate request failed after multiple attempts. This can happen, for example, if your DNS configuration is not correct, you run into Let’s Encrypt™ quota limits, or the domain validation process failed for some other reason. There won’t be any further automatic attempts. If you need assistence please contact us via [email protected].

These are reported as certificate state by the endpoints.

API Endpoints

The KraftCloud Services REST API provides the following endpoints:

Method	Endpoint	Purpose and Description
GET	/v1/certificates	Returns the current state and properties of certificates
DELETE	/v1/certificates	Deletes the specified certificates
GET	/v1/certificates/list	Lists all existing certificates

In the following, the API endpoints are specified relative to this base URL:

https://api.X.kraft.cloud/

With X being the IATA metro code. We use fra0 as an example in the documentation. See the introduciton for more information on how to connect to the API.

Local Scope

Local API endpoints directed at a specific certificate additionally include the UUID of the certificate (i.e., GET /v1/certificates/<UUID>)

Getting the Status of a Certificate

Returns the current status and the properties of a certificate.

Batching

In global scope, you can specify an array of status requests to retrieve the status of multiple certificates with the same call.

Request

Endpoints:
GET /v1/certificates
GET /v1/certificates/<UUID>

Parameter	Type	Default	Required	Description
uuid | name1	UUID | Name		✔️	UUID or name of the certificate to get the status for

¹ Not allowed in local scope. You need to specify either uuid or name.

Example of getting the status of a certificate

curl -X GET \
     -H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/certificates/0b8fda39-d326-426e-827e-093e4c173dc8"

Response

The response is embedded in a JSON object as described in API Responses.

Field	Type	Description
status	string	success on success, or error if the request failed
uuid	UUID	UUID of the group
name	Name	Name of the group
created_at	string	Date and time of creation in ISO8601
common_name	string	Common name of the certificate
state	State	Current state of the certificate
validation	object	Validation status (only while pending)
attempt	int	Number of validation attempts made
next	string	Date and time of next validation attempt in ISO8601
subject	string	Certificate subject
issuer	string	Certificate issuer (usually Let’s Encrypt)
serial_number	string	Certificate serial number
not_before	string	Date and time of beginning of validity in ISO8601
not_after	string	Expiration date and time in ISO8601
service_groups	array of objects	Service groups using this certificate
uuid	UUID	UUID of the group
name	Name	Name of the group

Status 200 OK

{
  "status": "success",
  "data": {
    "certificates": [
      {
        "status": "success",
        "uuid": "0b8fda39-d326-426e-827e-093e4c173dc8",
        "name": "example.com-x9d9k",
        "created_at": "2024-03-07T19:06:04Z",
        "common_name": "example.com",
        "state": "valid",
        "subject": "CN=example.com",
        "issuer": "CN=R3,O=Let's Encrypt,C=US",
        "serial_number": "1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F",
        "not_before": "2024-03-07T19:06:11Z",
        "not_after": "2024-06-05T19:06:10Z",
        "service_groups": [
          {
            "uuid": "3b5b4c36-2c9b-46e4-80c6-7e5b561938c2",
            "name": "young-monkey-uq6dxq0u"
          }
        ]
      }
    ]
  }
}

Status 200 OK - Certificate Request Pending

{
  "status": "success",
  "data": {
    "certificates": [
      {
        "status": "success",
        "uuid": "0b8fda39-d326-426e-827e-093e4c173dc8",
        "name": "example.com-x9d9k",
        "created_at": "2024-03-07T19:06:04Z",
        "common_name": "example.com",
        "state": "pending",
        "validation": {
          "attempt": 2,
          "next": "2024-03-07T19:16:04Z"
        },
        "service_groups": [
          {
            "uuid": "3b5b4c36-2c9b-46e4-80c6-7e5b561938c2",
            "name": "young-monkey-uq6dxq0u"
          }
        ]
      }
    ]
  }
}

Deleting a Certificate

Deletes the specified certificate. Fails if the certificate is still attached to a service group. After this call the IDs associated with the certificate are no longer valid.

Soft Delete

While deleting a certificate does delete the certificate object, KraftCloud will keep your certificate files (i.e., the signed certificate chain and private key). When you request a certificate for the same domain, the original certificate files are restored. This is too protect you from running into Let’s Encrypt™ rate limits. If you want to permanently delete the certificate files or generate fresh ones, please contact us via [email protected].

Batching

In global scope, you can specify an array of delete requests to delete multiple certificates with the same call.

Request

Endpoints:
DELETE /v1/certificates
DELETE /v1/certificates/<UUID>

Parameter	Type	Default	Required	Description
uuid | name1	UUID | Name		✔️	UUID or name of the certificate to delete

¹ Not allowed in local scope. You need to specify either uuid or name.

Example of deleting a specific certificate

curl -X DELETE \
     -H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/certificates/0b8fda39-d326-426e-827e-093e4c173dc8"

Response

The response is embedded in a JSON object as described in API Responses.

Field	Type	Description
status	string	success on success, or error if the request failed
uuid	UUID	UUID of the certificate
name	Name	Name of the certificate

Status 200 OK

{
  "status": "success",
  "data": {
    "certificates": [
      {
        "status": "success",
        "uuid": "0b8fda39-d326-426e-827e-093e4c173dc8",
        "name": "example.com-x9d9k"
      }
    ]
  }
}

List Existing Certificates

Lists all existing certificates. You can filter by common name. The returned groups fulfill all provided filter criteria. No particular value is assumed if a filter is not part of the request.

Request

Endpoints:
GET /v1/certificates/list

Parameter	Type	Default	Required	Description
common_name	string			Common name of the certificate

Example of listing all existing certificates

curl -X GET \
     -H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/certificates/list"

Example of looking up the certificate for a specific common name

curl -X GET \
     -H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
     -H "Content-Type: application/json" \
     "https://api.fra0.kraft.cloud/v1/services/list" \
     -d '{
        "common_name": "example.com"
      }'

Response

The response is embedded in a JSON object as described in API Responses.

Field	Type	Description
uuid	UUID	UUID of the group
name	Name	Name of the group

Status 200 OK

{
  "status": "success",
  "data": {
    "service_groups": [
      {
        "uuid": "0b8fda39-d326-426e-827e-093e4c173dc8",
        "name": "example.com-x9d9k"
      }
    ]
  }
}