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:
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.
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>
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1 | UUID | Name | ✔️ | UUID or name of the certificate to get the status for |
1 Not allowed in local scope.
You need to specify either uuid
or name
.
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 |
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.
Request
Endpoints:
DELETE /v1/certificates
DELETE /v1/certificates/<UUID>
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1 | UUID | Name | ✔️ | UUID or name of the certificate to delete |
1 Not allowed in local scope.
You need to specify either uuid
or name
.
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 |
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 |
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 |