Mint a new bus certificate covering the given names.
const url = 'https://example.com/api/v1/settings/bus/certificate';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"names":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/settings/bus/certificate \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "names": [ "example" ] }'Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Which names a regenerated bus certificate should cover.
object
Hostnames and IP addresses remote pollers will dial, added to the deployment’s internal defaults. A poller’s connection fails unless the exact address it dials is present, so this is the field that decides whether a new site can connect.
Examplegenerated
{ "names": [ "example" ]}Responses
Section titled “Responses”Generated and written; the body is the new certificate’s details
The bus, as Settings ▸ Pollers shows it.
object
Whether the switch below can be operated. false means the updater sidecar that performs it
is not deployed, is switched off, or has stopped reporting — the certificate is still
readable, but turning remote acceptance on or off needs a shell on the host.
The certificate the bus serves, or null if none has been established yet.
object
The certificate in PEM. This is what a remote poller uses as its YAGRA_BUS_CA_FILE — a
self-signed certificate is its own certificate authority. Safe to distribute; the private
key never leaves the server.
Days until expiry; negative once it has passed.
Lowercase hex SHA-256 of the certificate. Compare it against the file a site was given to confirm the site is holding this certificate and not an older one.
When this certificate was generated, RFC 3339.
The account that asked for it, if a signed-in user did. Empty for the one generated automatically before the bus first started.
Distinguished name of the issuer. Equal to subject, because this certificate is
self-signed.
Key type and size, for example ECDSA P-256.
Whether the private key can still be decrypted. false means the encryption key has changed
or been lost, and a new certificate has to be generated — which every remote site must then
be given.
Whether the files the bus reads match this certificate. false means it is stored but has
not reached the volume yet — the bus is still serving whatever it started with.
End of the validity window, RFC 3339.
Start of the validity window, RFC 3339.
The hostnames and IP addresses this certificate is valid for. A remote poller’s connection fails unless the exact address it dials appears here.
Distinguished name of the certificate’s subject.
Whether this core is talking to the bus over TLS, which is what accepting remote-site pollers requires.
Examplegenerated
{ "can_switch": true, "certificate": { "certificate": "example", "expires_in_days": 1, "fingerprint_sha256": "example", "issued_at": "example", "issued_by": "example", "issuer": "example", "key_algorithm": "example", "key_unreadable": true, "materialized": true, "not_after": "example", "not_before": "example", "sans": [ "example" ], "subject": "example" }, "remote_enabled": true}A supplied name is not a usable hostname or IP address
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}No valid bearer token
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Role lacks ManageSystem
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}This deployment has no bus certificate store
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}