TLS check reference

The full request/response schema is in the auto-generated API Reference. This page is the human-readable cheat sheet.

Object: `TlsJob`

Field	Type	Description
`id`	uuid	TLS check ID.
`account_id`	uuid	Owning account.
`http_job_id`	uuid	The HTTP check this TLS check was paired with on creation.
`current_status`	enum	See status table below.
`domain`	string	Hostname extracted from the HTTP check’s URL.
`port`	int	Port the handshake connects to. `443` unless set with `tls_port` on the HTTP check.
`expiry_date`	rfc3339 \| null	Cert’s `notAfter` (set after first successful handshake).
`last_run_at`	rfc3339 \| null	Most recent handshake timestamp.
`last_status_change_at`	rfc3339 \| null	When `current_status` last transitioned.
`created_at`	rfc3339	When the TLS check was first provisioned.
`alert_on_invalid_certificate`	bool	Whether an invalid certificate alerts.
`certificate_problem`	enum \| null	Why browsers would reject the certificate, from the latest judgment. See certificate problems. `null` when it is valid or not judged yet.
`certificate_checked_at`	rfc3339 \| null	When the certificate was last judged, by an uptime check or the TLS check.
`certificate_problem_since`	rfc3339 \| null	When the current problem was first seen. `null` without a problem.

Status enum

Status	Meaning
`good`	Most recent handshake succeeded and the certificate has not expired. The chain and hostname match are recorded but do not change the status.
`bad`	The certificate has expired.
`unknown`	The check has not run yet, or could not connect or read a certificate (DNS failure, refused or timed-out connection, nothing serving TLS on the port).

A TLS check that stays unknown for more than 24 hours means certificate expiry is not being watched. Site Qwality emails the account owners once per stretch and records a tls_unknown monitor event on the HTTP check. A wrong port is a common cause: set tls_port.

Certificate problems

`certificate_problem`	Meaning
`expired`	The certificate, or one in its chain, has expired.
`not_yet_valid`	The certificate, or one in its chain, is not valid yet.
`self_signed`	The certificate is signed by its own key, not by a certificate authority.
`untrusted_chain`	The chain does not lead to a root in the Mozilla root store: an intermediate is missing, the issuer is unknown, or a signature does not verify.
`hostname_mismatch`	The certificate does not cover the hostname.

When several apply, the first in this table is named.

Invalid certificate alerts

Send alert_on_invalid_certificate on POST /http/job or PUT /http/job/{job_id} to switch the alert on or off. It defaults to true when TLS monitoring starts, a PUT without it keeps the current value, and it is ignored without monitor_tls. GET /http/job/{job_id} returns it when TLS monitoring is on.

The alert fires after two invalid judgments in a row, with the event tls.invalid on webhooks, and its recovery is tls.recovered. On PagerDuty and Opsgenie the two share the key sq-tls-invalid-<tls_job_id>-<alert-id>, so the recovery resolves what the alert opened.

The TLS check is read-only via its own endpoints (you create it implicitly by setting monitor_tls: true on an HTTP check):

Method	Path	Purpose
`GET`	`/tls/job/{tls_job_id}`	Fetch current status.
`GET`	`/tls/job/{tls_job_id}/recent`	Recent handshake results.

To enable/disable TLS monitoring, PUT /http/job/{job_id} with monitor_tls: true|false.

Port

The handshake connects to port 443 by default. To check a certificate served elsewhere, send tls_port (1 to 65535) on POST /http/job or PUT /http/job/{job_id}. GET /http/job/{job_id} returns the port in use as tls_port when TLS monitoring is on.

Request	Result
`tls_port` outside 1 to 65535	`400`.
`tls_port` with `monitor_tls: false`	`400`.
`PUT` with `tls_port` on a check without TLS monitoring and no `monitor_tls`	`409`. Send `monitor_tls: true` with it.