Certificates

Server

Unikraft Cloud allows you to host your deployment at subdomains of the intended metro and/or use custom domains (e.g., example.com). Typically, Unikraft Cloud will automatically generate a TLS certificate for you based on Let's Encrypt™ via a DNS-01 challenge.

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

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.

List Certificates

GET

https://api.sfo.unikraft.cloud

/v1/certificates

List certificates.

List Certificates › query Parameters

uuid

string[]

The UUID of the resource.

name

string[]

The name of the resource.

details

boolean

count

integer · uint32

from

string

order

Common.PaginationOrder · enum

The sort order used by list endpoints.

Enum values:

asc

desc

sortby

Common.PaginationSortBy · enum

The sort field used by list endpoints.

Enum values:

create_time

List Certificates › Request Body optional

Common.NameOrUUID[]

An identifier for a resource — either a name or a UUID, but not both.

Common.NameOrUUID

uuid

string · uuid

The UUID of the resource.

name

string

The name of the resource.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: uuid
	type = object · requires: name

Properties for Variant 1:

uuid

string · uuid · required

The UUID of the resource.

name

string

The name of the resource.

List Certificates › Responses

200

The request has succeeded.

The response message for getting one or more certificate(s) given their UUID(s) or name(s).

Certificates.GetCertificatesResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

GET/v1/certificates

curl https://api.sfo.unikraft.cloud/v1/certificates \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name"
  }
]'

Example Request Body

[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "certificates": [
      {
        "status": "success",
        "message": "message",
        "error": 0,
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "node": "node",
        "created_at": "2024-08-25T15:00:00Z",
        "common_name": "my-common-name",
        "subject": "example.com",
        "issuer": "CN=R10,O=Let's Encrypt,C=US",
        "serial_number": "123456789ABCDEF123456789ABCDEF123456",
        "not_before": "2024-08-25T15:00:00Z",
        "not_after": "2024-08-25T15:00:00Z",
        "state": "pending",
        "validation": {
          "attempt": 0,
          "next": "2024-08-25T15:00:00Z"
        },
        "service_groups": [
          {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "name": "name",
            "node": "node"
          }
        ]
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Update Certificates

PUT

https://api.sfo.unikraft.cloud

/v1/certificates

Update certificates.

Update Certificates › Request Body

Certificates.UpdateCertificatesRequestItem[]

A single update operation to be applied to a certificate.

Certificates.UpdateCertificatesRequestItem

chain

string · required

The new certificate chain. This is the public chain of the certificate in PEM format. The chain should include the certificate and any intermediate certificates.

pkey

string · required

The new private key. This is the private key of the certificate in PEM format. The private key must match the public key in the certificate chain.

uuid

string · uuid

The UUID of the resource.

name

string

The name of the resource.

Update Certificates › Responses

200

The request has succeeded.

The response message for updating one or more certificate(s) given their UUID(s) or name(s).

Certificates.UpdateCertificatesResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

PUT/v1/certificates

curl https://api.sfo.unikraft.cloud/v1/certificates \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name",
    "chain": "chain",
    "pkey": "pkey"
  }
]'

Example Request Body

[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name",
    "chain": "chain",
    "pkey": "pkey"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "certificates": [
      {
        "status": "success",
        "message": "message",
        "error": 0,
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "node": "node",
        "created_at": "2024-08-25T15:00:00Z",
        "common_name": "my-common-name",
        "subject": "example.com",
        "issuer": "CN=R10,O=Let's Encrypt,C=US",
        "serial_number": "123456789ABCDEF123456789ABCDEF123456",
        "not_before": "2024-08-25T15:00:00Z",
        "not_after": "2024-08-25T15:00:00Z",
        "state": "pending",
        "validation": {
          "attempt": 0,
          "next": "2024-08-25T15:00:00Z"
        },
        "service_groups": [
          {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "name": "name",
            "node": "node"
          }
        ]
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Create Certificate

POST

https://api.sfo.unikraft.cloud

/v1/certificates

Upload a new certificate.

Create Certificate › Request Body

The request message for creating/uploading a new certificate.

Certificates.CreateCertificateRequest

chain

string · required

The certificate chain in PEM format. Required for user-uploaded certificates.

pkey

string · required

The private key in PEM format. Required for user-uploaded certificates.

name

string

The name of the resource. If not provided, a random name is generated. The name must be unique within the context of your account.

node

string

The name of the node to place the resource on. If not provided, the platform picks one. Only accepted on metros that span multiple nodes.

common_name

string

The common name (CN) of the certificate.

This must be a fully-qualified domain name (FQDN). Exactly one of cn or common_name must be specified.

Example: funky-town.com

Create Certificate › Responses

200

The request has succeeded.

The response message for creating a new certificate.

Certificates.CreateCertificateResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

POST/v1/certificates

curl https://api.sfo.unikraft.cloud/v1/certificates \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "name",
  "node": "node",
  "cn": "funky-town.com",
  "common_name": "funky-town.com",
  "chain": "chain",
  "pkey": "pkey"
}'

Example Request Body

{
  "name": "name",
  "node": "node",
  "cn": "funky-town.com",
  "common_name": "funky-town.com",
  "chain": "chain",
  "pkey": "pkey"
}

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "certificates": [
      {
        "status": "success",
        "message": "message",
        "error": 0,
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "node": "node",
        "created_at": "2024-08-25T15:00:00Z",
        "common_name": "my-common-name",
        "subject": "example.com",
        "issuer": "CN=R10,O=Let's Encrypt,C=US",
        "serial_number": "123456789ABCDEF123456789ABCDEF123456",
        "not_before": "2024-08-25T15:00:00Z",
        "not_after": "2024-08-25T15:00:00Z",
        "state": "pending",
        "validation": {
          "attempt": 0,
          "next": "2024-08-25T15:00:00Z"
        },
        "service_groups": [
          {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "name": "name",
            "node": "node"
          }
        ]
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Delete Certificates

DELETE

https://api.sfo.unikraft.cloud

/v1/certificates

Delete certificates by ID(s).

Delete Certificates › Request Body

Common.NameOrUUID[]

An identifier for a resource — either a name or a UUID, but not both.

Common.NameOrUUID

uuid

string · uuid

The UUID of the resource.

name

string

The name of the resource.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: uuid
	type = object · requires: name

Properties for Variant 1:

uuid

string · uuid · required

The UUID of the resource.

name

string

The name of the resource.

Delete Certificates › Responses

200

The request has succeeded.

The response message for deleting of one or more certificate(s) given their UUID(s) or name(s).

Certificates.DeleteCertificatesResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

DELETE/v1/certificates

curl https://api.sfo.unikraft.cloud/v1/certificates \
  --request DELETE \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name"
  }
]'

Example Request Body

[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "certificates": [
      {
        "status": "success",
        "message": "message",
        "error": 0,
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "node": "node"
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Get Certificate by UUID

GET

https://api.sfo.unikraft.cloud

/v1/certificates/{uuid}

Get a certificate by UUID.

Get Certificate by UUID › path Parameters

uuid

string · uuid · required

Get Certificate by UUID › Responses

200

The request has succeeded.

The response message for getting one or more certificate(s) given their UUID(s) or name(s).

Certificates.GetCertificatesResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

GET/v1/certificates/{uuid}

curl https://api.sfo.unikraft.cloud/v1/certificates/:uuid \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "certificates": [
      {
        "status": "success",
        "message": "message",
        "error": 0,
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "node": "node",
        "created_at": "2024-08-25T15:00:00Z",
        "common_name": "my-common-name",
        "subject": "example.com",
        "issuer": "CN=R10,O=Let's Encrypt,C=US",
        "serial_number": "123456789ABCDEF123456789ABCDEF123456",
        "not_before": "2024-08-25T15:00:00Z",
        "not_after": "2024-08-25T15:00:00Z",
        "state": "pending",
        "validation": {
          "attempt": 0,
          "next": "2024-08-25T15:00:00Z"
        },
        "service_groups": [
          {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "name": "name",
            "node": "node"
          }
        ]
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Update Certificate by UUID

PUT

https://api.sfo.unikraft.cloud

/v1/certificates/{uuid}

Update a certificate by UUID.

Update Certificate by UUID › path Parameters

uuid

string · uuid · required

Update Certificate by UUID › Request Body

The request body for updating a certificate by its UUID or name.

Certificates.UpdateCertificateByUUIDRequestBody

chain

string · required

The new certificate chain. This is the public chain of the certificate in PEM format. The chain should include the certificate and any intermediate certificates.

pkey

string · required

The new private key. This is the private key of the certificate in PEM format. The private key must match the public key in the certificate chain.

Update Certificate by UUID › Responses

200

The request has succeeded.

The response message for updating one or more certificate(s) given their UUID(s) or name(s).

Certificates.UpdateCertificatesResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

PUT/v1/certificates/{uuid}

curl https://api.sfo.unikraft.cloud/v1/certificates/:uuid \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "chain": "chain",
  "pkey": "pkey"
}'

Example Request Body

{
  "chain": "chain",
  "pkey": "pkey"
}

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "certificates": [
      {
        "status": "success",
        "message": "message",
        "error": 0,
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "node": "node",
        "created_at": "2024-08-25T15:00:00Z",
        "common_name": "my-common-name",
        "subject": "example.com",
        "issuer": "CN=R10,O=Let's Encrypt,C=US",
        "serial_number": "123456789ABCDEF123456789ABCDEF123456",
        "not_before": "2024-08-25T15:00:00Z",
        "not_after": "2024-08-25T15:00:00Z",
        "state": "pending",
        "validation": {
          "attempt": 0,
          "next": "2024-08-25T15:00:00Z"
        },
        "service_groups": [
          {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "name": "name",
            "node": "node"
          }
        ]
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Delete Certificate by UUID

DELETE

https://api.sfo.unikraft.cloud

/v1/certificates/{uuid}

Delete a certificate by UUID.

Delete Certificate by UUID › path Parameters

uuid

string · uuid · required

Delete Certificate by UUID › Responses

200

The request has succeeded.

The response message for deleting of one or more certificate(s) given their UUID(s) or name(s).

Certificates.DeleteCertificatesResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

Images Autoscale