Skip to content

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:

StateDescription
pendingThe 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
validThe certificate is valid and can be used by your services
errorThe 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:

MethodEndpointPurpose and Description
POST/v1/certificatesUploads an existing certificate
GET/v1/certificatesReturns the current state and properties of certificates
DELETE/v1/certificatesDeletes the specified certificates
GET/v1/certificates/listLists 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.

Uploading an Existing Certificate

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

Request

Endpoints:
POST /v1/certificates

Body ParameterTypeDefaultRequiredDescription
name1NameThe name of the certificate to upload
cnstring✔️The common name of the certificate
chainstring✔️The chain of the certificate in PEM format
pkeystring✔️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': '[...]',
}"

1 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.

FieldTypeDescription
uuidUUIDUUID of the certificate
nameNameName 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.

Request

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

Query ParameterTypeDefaultRequiredDescription
detailsbooltrueWhether to provide detailed status and configuration information
name1string | list of stringsNames of certificates to return as comma-separated list
uuid1string | list of stringsUUIDs of certificates to return as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the certificate to get the status for

1 Not allowed in local scope.
2 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"
Terminal window
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"
}
]'
Terminal window
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/certificates?name=my-certificate,my-other-certificate"
Terminal window
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.

FieldTypeDescription
status1stringsuccess on success, or error if the request failed
uuidUUIDUUID of the certificate
nameNameName of the certificate
created_atstringDate and time of creation in ISO8601
common_namestringCommon name of the certificate
stateStateCurrent state of the certificate
validationobjectValidation status (only while pending)
    attemptintNumber of validation attempts made
    nextstringDate and time of next validation attempt in ISO8601
subjectstringCertificate subject
issuerstringCertificate issuer (usually Let’s Encrypt)
serial_numberstringCertificate serial number
not_beforestringDate and time of beginning of validity in ISO8601
not_afterstringExpiration date and time in ISO8601
service_groupsarray of objectsServices using this certificate
    uuidUUIDUUID of the service
    nameNameName of the service

1 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.

Request

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

Query ParameterTypeDefaultRequiredDescription
name1string | list of stringsNames of certificates to delete as comma-separated list
uuid1string | list of stringsUUIDs of certificates to delete as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the certificate to delete

1 Not allowed in local scope.
2 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.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
uuidUUIDUUID of the certificate
nameNameName 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.

Request

Endpoints:
GET /v1/certificates/list

Body ParameterTypeDefaultRequiredDescription
common_namestringCommon 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.

FieldTypeDescription
uuidUUIDUUID of the certificates
nameNameName of the certificates
Status 200 OK
{
"status": "success",
"data": {
"certificates": [
{
"uuid": "0b8fda39-d326-426e-827e-093e4c173dc8",
"name": "example.com-x9d9k"
}
]
}
}