Skip to content

Certificates

TLS certificates for HTTPS listeners.

Paths are relative to your API address. See Authentication and Operations. Changes that answer 202 Accepted return an operation to follow.

Request and response examples are generated from the schema; the tables under Schemas are the reference.

List certificates

GET /v1/orgs/{org_id}/projects/{project_id}/certificates

The project's TLS certificates in every location, with their expiry and the listeners that serve them. Never their keys.

Input parameters

Parameter In Type Default Nullable Description
Authorization header string N/A No Bearer followed by a service account's API key. The console uses your signed-in session instead.
location query string Yes
org_id path string No
project_id path string No

Responses

{
    "items": [
        {
            "chain_length": 0,
            "created_at": "2022-04-13T15:42:05.901Z",
            "days_left": 0,
            "display_name": "string",
            "error": "string",
            "fingerprint_sha256": "string",
            "id": "string",
            "in_use_by": [
                {
                    "listener_id": "string",
                    "listener_name": "string",
                    "port": 0,
                    "protocol": "string",
                    "role": "default"
                }
            ],
            "key_bits": 0,
            "key_type": "string",
            "last_operation": "string",
            "location": "string",
            "names": [
                "string"
            ],
            "not_after": "2022-04-13T15:42:05.901Z",
            "not_before": "2022-04-13T15:42:05.901Z",
            "state": "string",
            "subject": "string"
        }
    ]
}

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Upload a certificate

POST /v1/orgs/{org_id}/projects/{project_id}/certificates

Uploads a TLS certificate, its chain and its private key to one location, for HTTPS load balancers. Checked at once (the key must be the certificate's, the certificate valid for at least another day and the chain in order); the key is then sealed and delivered into the location's key manager, and never shown again. Accepted at once: follow the returned operation until it finishes.

Input parameters

Parameter In Type Default Nullable Description
Authorization header string N/A No Bearer followed by a service account's API key. The console uses your signed-in session instead.
idempotency-key header string Yes
org_id path string No
project_id path string No

Request body

{
    "certificate": "string",
    "chain": "string",
    "display_name": "string",
    "execute_before": "2022-04-13T15:42:05.901Z",
    "location": "string",
    "private_key": "string"
}

Responses

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Delete a certificate

DELETE /v1/orgs/{org_id}/projects/{project_id}/certificates/{certificate_id}

Deletes the certificate and its key from the location's key manager. Refused while a load balancer listener serves it: switch the listener to another certificate first. Accepted at once: follow the returned operation until it finishes.

Input parameters

Parameter In Type Default Nullable Description
Authorization header string N/A No Bearer followed by a service account's API key. The console uses your signed-in session instead.
certificate_id path string No
idempotency-key header string Yes
org_id path string No
project_id path string No

Responses

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get a certificate

GET /v1/orgs/{org_id}/projects/{project_id}/certificates/{certificate_id}

One certificate's subject, names, validity, fingerprint and the listeners that serve it. Never its key.

Input parameters

Parameter In Type Default Nullable Description
Authorization header string N/A No Bearer followed by a service account's API key. The console uses your signed-in session instead.
certificate_id path string No
org_id path string No
project_id path string No

Responses

{
    "chain_length": 0,
    "created_at": "2022-04-13T15:42:05.901Z",
    "days_left": 0,
    "display_name": "string",
    "error": "string",
    "fingerprint_sha256": "string",
    "id": "string",
    "in_use_by": [
        {
            "listener_id": "string",
            "listener_name": "string",
            "port": 0,
            "protocol": "string",
            "role": "default"
        }
    ],
    "key_bits": 0,
    "key_type": "string",
    "last_operation": "string",
    "location": "string",
    "names": [
        "string"
    ],
    "not_after": "2022-04-13T15:42:05.901Z",
    "not_before": "2022-04-13T15:42:05.901Z",
    "state": "string",
    "subject": "string"
}

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Schemas

Accepted

Name Type Description
operation OperationLink

CertificateCreateBody

Name Type Description
certificate string The certificate, PEM (the leaf only).
chain string | null Intermediate certificates, PEM, the leaf's issuer first, at most 5.
display_name string
execute_before string(date-time) | null
location string
private_key string The certificate's private key, PEM, unencrypted: RSA of at least 2048 bits, or EC on P-256 or P-384. Never shown back.

CertificateList

Name Type Description
items Array<CertificateView>

CertificateListener

Name Type Description
listener_id string
listener_name string | null Null for a listener with no name.
port integer | null
protocol string | null As inventory last read it.
role string default: the listener serves it to a client whose host name no other certificate covers; sni: only to a client asking for one of its names.

CertificateView

Name Type Description
chain_length integer
created_at string(date-time)
days_left integer Whole days until not_after (negative once expired).
display_name string
error string | null
fingerprint_sha256 string
id string crt_…
in_use_by Array<CertificateListener>
key_bits integer
key_type string
last_operation string | null
location string
names Array<string> The DNS names and addresses it covers.
not_after string(date-time)
not_before string(date-time)
state string creating, active, error, create_failed or deleting.
subject string

HTTPValidationError

Name Type Description
detail Array<ValidationError>
Name Type Description
href string Where to read the operation; also the Location header.
id string The operation's ID (op_…).
state string | null Its state when accepted, normally queued.

ValidationError

Name Type Description
ctx
input
loc Array<>
msg string
type string