Import a certificate and its private key.

PUT

/api/v1/settings/tls

curl --request PUT \
  --url https://example.com/api/v1/settings/tls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "certificate": "example", "private_key": "example" }'

Authorizations

• bearer

Request Body^required

Media typeapplication/json

A certificate chain and its private key, in PEM.

object

certificate

required

The full certificate chain in PEM, leaf first. A private key in this field is rejected — send it in private_key.

string

private_key

required

The matching private key in PEM: PKCS#8, PKCS#1 or SEC1, and not passphrase-protected. Never returned by any endpoint.

string

Example^generated

{
  "certificate": "example",
  "private_key": "example"
}

Responses

200

Imported and live; the body is the new certificate’s details

Media typeapplication/json

The WebUI’s TLS certificate, plus one fact about how this deployment is exposed.

object

api_port_is_public

required

Whether Yagra’s API port is reachable beyond the server itself. When true, the API is also available over plain HTTP on that port, so the encrypted WebUI is not the only way in.

boolean

config

One of:

null

null

object

The certificate being served, or null if none has been established yet.

object

certificate

required

The certificate chain in PEM, leaf first. Safe to distribute — this is what a client would add to a trust store or pass to curl --cacert.

string

expires_in_days

required

Days until expiry; negative once it has passed.

integer format: int64

fingerprint_sha256

required

Lowercase hex SHA-256 of the certificate, matching what a browser displays.

string

imported_at

required

When this certificate was imported or generated, RFC 3339.

string

imported_by

The account that imported it, if it was imported by a signed-in user.

string | null

issuer

required

Distinguished name of the issuer. Equal to subject for a self-signed certificate.

string

key_algorithm

required

Key type and size, for example RSA-2048 or ECDSA P-256.

string

key_unreadable

required

Whether the private key can still be decrypted. false means the encryption key has changed or been lost: the certificate cannot be served or renewed until it is imported again.

boolean

materialized

required

Whether the web server is currently serving this certificate. false means it is stored but has not reached the web container yet.

boolean

not_after

required

End of the validity window, RFC 3339.

string

not_before

required

Start of the validity window, RFC 3339.

string

sans

required

The hostnames and IP addresses this certificate is valid for.

Array<string>

source

required

Where a certificate came from, and therefore whether core may replace it on its own.

string

Allowed values: self_signed imported unknown

subject

required

Distinguished name of the certificate’s subject.

string

Example

{
  "config": {
    "source": "self_signed"
  }
}

400

The pair is not usable; the message says which of the checks it failed

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks the manage-configuration permission

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

This deployment has no certificate store

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}