Harthelm Docs
REST APICli

Start a CLI sign-in

`hart login`. Works without credentials; rate-limited per client address (429). The CLI sends the S256 challenge of a verifier only it knows (PKCE, RFC 7636), so nobody but the CLI can redeem the sign-in. - `loopback`: the CLI listens on `127.0.0.1:<redirect_port>` and opens `verification_url`; after the approval the console navigates to `http://127.0.0.1:<redirect_port>/callback` and the CLI redeems. - `code` (`hart login --code`, for SSH sessions and workspaces): the CLI prints `verification_url` and `user_code` and polls the redeem every `interval` seconds. A sign-in expires after 10 minutes. `Idempotency-Key` is accepted like on any create, but a CLI sends none.

Generated from openapi/harthelm.yaml at v1.5.0
POST
/cli/logins

Header Parameters

Idempotency-Key?string

Client-chosen key (at most 255 characters); a repeated key returns the first result for 24 h.

Length1 <= length <= 255

Request Body

application/json
  1. body
mode*CliLoginMode
Value in"loopback""code"
code_challenge*string

BASE64URL(SHA-256(code_verifier)) without padding (PKCE S256).

Match^[A-Za-z0-9_-]{43}$
redirect_port?integer

loopback only (required there): the CLI's port on 127.0.0.1.

Range1024 <= value <= 65535
name?ApiKeyName

1 to 100 characters without leading or trailing spaces; need not be unique.

Match^\S(.*\S)?$
Length1 <= length <= 100
hostname*string

The machine hart runs on, shown in the console before the approval and in the default key name.

Length1 <= length <= 255
os?string

GOOS/GOARCH of the CLI, shown in the console.

Lengthlength <= 64
cli_version*string
Lengthlength <= 64

Response Body

The sign-in, pending.

application/json
  1. response
id*string
Formatuuid
mode*CliLoginMode
Value in"loopback""code"
user_code*string

Eight letters as XXXX-XXXX from an alphabet without vowels and look-alikes.

verification_url*string

<console>/cli-login?code=<user_code>: the page that shows the request and asks for the approval.

expires_at*string
Formatdate-time
interval*integer

Seconds between two redeem polls.

Range1 <= value
curl -X POST 'https://console.example.com/api/v1/cli/logins' \  -H 'Content-Type: application/json' \  -d '{  "mode": "loopback",  "code_challenge": "string",  "hostname": "string",  "cli_version": "string"}'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "mode": "loopback",  "user_code": "string",  "verification_url": "string",  "expires_at": "2019-08-24T14:15:22Z",  "interval": 1}

Redeem an approved CLI sign-in

Works without credentials; the `code_verifier` is the proof. `202` while nobody approved yet (poll again after `interval` seconds); `200` once, with a new API key of the approving user (source `cli`, name from the start request); afterwards, and after a denial or the expiry, `409 cli-login-closed`. A wrong verifier is `404`, like an unknown sign-in.

Add a custom domain

Team admins (`team.manage`). The domain is unverified until a check finds its TXT record `_harthelm.<name>` (the record of purpose `verification`; a CNAME or A record only routes and never proves ownership); only a verified domain gets an edge object, a certificate and traffic. An unverified domain is a claim that expires: at `expires_at` (`customDomains.claimDays` after its creation, 7 by default) it is removed and the name is free again. 409 `domain-taken` when any team has the name, `domain-reserved` for the console host and names under the workspace domain, `domain-limit` when the team has `customDomains.maxPerTeam` domains; 409 `custom-domains-disabled` when the installation has none; 429 `domain-create-rate` (with `Retry-After`) when the team added `customDomains.createPerTeamPerHour` domains in the last hour (each verified domain costs an ACME order on the installation's shared account).