Certificates

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

Certificates for Custom Domains

Unikraft Cloud 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 Unikraft Cloud metro.

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

For wildcard domains you have to supply your own certificate. If you want to use Let’s Encrypt™ you can use their DNS-based challenge and upload the resulting certificate to Unikraft Cloud.

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 support@unikraft.cloud.

These are reported as certificate state by the endpoints.

API Endpoints

The Unikraft Cloud Services API provides the following endpoints:

Method	Endpoint	Purpose and Description
POST	/v1/certificates	Uploads an existing certificate
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>)

Uploading an Existing Certificate

Create a new certificate object and upload an existing certificate chain and private key.

Batching

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

Request

Endpoints:
POST /v1/certificates

Body Parameter	Type	Default	Required	Description
name1	Name			The name of the certificate to upload
cn	string		✔️	The common name of the certificate
chain	string		✔️	The chain of the certificate in PEM format
pkey	string		✔️	The private key of the certificate in PEM format

Example of uploading a certificate

curl -X POST \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     -H "Content-Type: application/json" \
     "https://api.fra0.kraft.cloud/v1/certificates/" \
     -d "{
        'name': 'my-certificate',
        'cn': '*.example.com',
        'chain': '[...]'
        'pkey': '[...]',
     }"

¹ If no name is specified a random name of the form <cn>-X is auto-generated, where <cn> is the common name and X is a 5 character long random alphanumeric suffix. For wildcard domains the wildcard part is cut off.

Response

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

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

Status 200 OK

{
  "status": "success",
  "data": {
    "certificates": [
      {
        "uuid": "0b8fda39-d326-426e-827e-093e4c173dc8",
        "name": "my-certificate"
      }
    ]
  }
}

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.

Listing All Existing Certificates

In global scope, do not provide any IDs via body or query parameters if you want to list all existing certificates.

Request

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

Query Parameter	Type	Default	Required	Description
details	bool	true		Whether to provide detailed status and configuration information
name1	string | list of strings			Names of certificates to return as comma-separated list
uuid1	string | list of strings			UUIDs of certificates to return as comma-separated list

Body Parameter	Type	Default	Required	Description
uuid | name1,2	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 within the same body object.

Example of getting the status of certificates

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

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/certificates" \
     -d '[
      {
        "uuid": "0b8fda39-d326-426e-827e-093e4c173dc8"
      },
      {
        "name": "my-certificate"
      }
     ]'

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/certificates?name=my-certificate,my-other-certificate"

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/certificates?details=false"

Response

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

Field	Type	Description
status1	string	success on success, or error if the request failed
uuid	UUID	UUID of the certificate
name	Name	Name of the certificate
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	Services using this certificate
uuid	UUID	UUID of the service
name	Name	Name of the service

¹ Not when listing all existing certificates.

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. After this call the IDs associated with the certificate are no longer valid.

Soft Delete

While deleting a certificate does delete the certificate object, Unikraft Cloud 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 support@unikraft.cloud.

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>

Query Parameter	Type	Default	Required	Description
name1	string | list of strings			Names of certificates to delete as comma-separated list
uuid1	string | list of strings			UUIDs of certificates to delete as comma-separated list

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

¹ Not allowed in local scope.
² You need to specify either uuid or name within the same body object.

Example of deleting a specific certificate

curl -X DELETE \
     -H "Authorization: Bearer ${UKC_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 certificates fulfill all provided filter criteria. No particular value is assumed if a filter is not part of the request.

Caution

This endpoint has been deprecated and will be removed in future versions. Use GET /v1/certificates instead.

Request

Endpoints:
GET /v1/certificates/list

Body 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 ${UKC_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 ${UKC_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 certificates
name	Name	Name of the certificates

Status 200 OK

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