Harthelm Docs
REST APIDomains

Use an uploaded certificate

Team admins (`team.manage`). Switches the domain to `tls.mode` `self-managed`: the chain must parse, cover the domain's name, not be expired, and match the private key (422 at `/certificate_pem` or `/private_key_pem`). The key is stored sealed and rendered into the edge object's TLS Secret; it is never returned.

Generated from openapi/harthelm.yaml at v1.5.0
PUT
/teams/{team}/domains/{domain}/certificate

Authorization

cookie__Host-harthelm_session<token>

Browser session of the UI (12 h idle, 7 days absolute). State-changing requests also need the header Harthelm-CSRF: 1 and a matching Origin.

Path Parameters

team*integer

Numeric resource id.

Formatint64
Range1 <= value
domain*string

A custom domain's name, e.g. shop.example.com.

Length3 <= length <= 253

Request Body

application/json
  1. body
certificate_pem*string

The leaf certificate first, then the intermediates.

Lengthlength <= 65536
private_key_pem*string
Lengthlength <= 16384

Response Body

The domain.

application/json
  1. response
id*string
Formatuuid
team_id*ID

Numeric resource id.

Formatint64
Range1 <= value
name*DomainNameValue

A host name of at least two labels (letters, digits, hyphens; IDNs in their xn-- form), compared in lower case; no wildcard, no IP address, no trailing dot.

Length3 <= length <= 253
url*string

The domain's HTTPS URL, from its name.

restricted*boolean
use_regex*boolean
max_body_bytes*integer

The effective limit (the installation default when none is set).

Formatint64
timeout_seconds*integer

The effective limit.

verification*
tls*
records*array<>

The DNS records to set, in the order the console shows them.

routes*array<>
created_by?ID

Numeric resource id.

Formatint64
Range1 <= value
created_at*string
Formatdate-time
updated_at*string
Formatdate-time
expires_at?string

An unverified domain (never verified): when the claim is released and the domain removed (its creation plus customDomains.claimDays). Absent once verified, and from an older core.

Formatdate-time
curl -X PUT 'https://console.example.com/api/v1/teams/1/domains/string/certificate' \  -H 'Content-Type: application/json' \  -d '{  "certificate_pem": "string",  "private_key_pem": "string"}'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "team_id": 1,  "name": "string",  "url": "string",  "restricted": true,  "use_regex": true,  "max_body_bytes": 0,  "timeout_seconds": 0,  "verification": {    "status": "unchecked",    "method": "txt",    "checked_at": "2019-08-24T14:15:22Z",    "verified_at": "2019-08-24T14:15:22Z",    "reason": "string",    "txt_missing_since": "2019-08-24T14:15:22Z",    "lapses_at": "2019-08-24T14:15:22Z"  },  "tls": {    "mode": "automated",    "status": "pending",    "reason": "string",    "not_after": "2019-08-24T14:15:22Z",    "covered_by": "string"  },  "records": [    {      "type": "CNAME",      "name": "string",      "value": "string",      "purpose": "verification"    }  ],  "routes": [    {      "path": "string",      "workspace_ids": [        1      ]    }  ],  "created_by": 1,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z"}

Change a custom domain's settings

Team admins (`team.manage`). Absent fields stay. Turning `use_regex` on or off re-validates the routes (422 at `/routes/<i>/path` when one does not fit the new mode).

Check the domain's DNS records now

Team admins (`team.manage`); the console's *Check status*. Enqueues a `domain_verify` job and answers at once with `verification.status` `checking`; follow `domain.updated` or poll the domain. Another check of the same domain within 10 seconds is 429. Only the TXT record verifies. A verified domain is checked again: without its TXT record it stays verified, but `verification.txt_missing_since` is set and it lapses at `verification.lapses_at`; a check that finds the record clears both and verifies a `lapsed` domain again. Core also re-checks every verified domain daily.