Harthelm Docs
REST APIAdmin

The licence and what it allows

Cluster admins only (`platform.admin`; `hart admin license`, the console's admin *Licence* page). Computes the state now: the licence in force, its state (`valid`, `expiring` from 60 days before its end, `grace` after the end, `restricted` after the grace period or without a valid licence), every licence installed so far with its standing, and what the limits count now and at their daily high of the last 90 days. A licence state never stops, scales down or deletes anything; `restricted` only refuses new teams, organizations, workspaces, managed services, domains, invitations and users (problem `license-restricted`).

Generated from openapi/harthelm.yaml at v1.5.0
GET
/admin/license

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.

Response Body

The licence status.

application/json
  1. response
state*LicenseState

valid: licensed. expiring: 60 days or less until the licence ends; nothing changes yet. grace: the licence ended (or an installation upgraded from 1.0.x has none yet) and everything still works until until. restricted: no valid licence; everything that exists keeps running, but new teams, organizations, workspaces, managed services, domains, invitations and users are refused (license-restricted).

Value in"valid""expiring""grace""restricted"
reason*string

licensed, ended, no-licence or upgrade-grace (an installation upgraded from 1.0.x without a licence); clients must accept other values.

message*string

One sentence for banners.

until?string

The next change of state; absent when restricted.

Formatdate-time
days_left*integer

Whole days until until; 0 when restricted.

active?
managed_by*string

values while the chart's license.existingSecret is set: the licence is changed in that Secret, and installing through the API answers 409.

Value in"api""values"
values_problem?string

Why the Secret's licence is not in force.

installation*string

This installation's id.

overage?string
Value in"soft""hard"
host_mismatch*boolean

The licence names console hosts and this one is not among them (a warning).

clock_behind*boolean

The clock is more than a day behind the latest time core has seen (a warning).

test_key*boolean

The licence in force is signed with the test key.

checked_at*string
Formatdate-time
usage*array<>
history*array<>

Every licence installed, newest first.

curl -X GET 'https://console.example.com/api/v1/admin/license'
{  "state": "valid",  "reason": "string",  "message": "string",  "until": "2019-08-24T14:15:22Z",  "days_left": 0,  "active": {    "id": "string",    "customer_id": "string",    "customer": "string",    "kind": "commercial",    "edition": "string",    "key_id": "string",    "start": "2019-08-24T14:15:22Z",    "end": "2019-08-24T14:15:22Z",    "last_day": "2019-08-24",    "grace_days": 0,    "grace_end": "2019-08-24T14:15:22Z",    "support_until": "2019-08-24",    "limits": {      "vcpus": 0,      "users": 0,      "workspaces": 0,      "nodes": 0    },    "overage": "soft",    "installations": [      "string"    ],    "hosts": [      "string"    ],    "note": "string",    "source": "api",    "installed_at": "2019-08-24T14:15:22Z",    "installed_by_email": "string",    "standing": "active",    "problem": "string",    "test_key": true  },  "managed_by": "api",  "values_problem": "string",  "installation": "string",  "overage": "soft",  "host_mismatch": true,  "clock_behind": true,  "test_key": true,  "checked_at": "2019-08-24T14:15:22Z",  "usage": [    {      "limit": "vcpus",      "current": 0,      "peak": 0,      "allowed": 0,      "over": true    }  ],  "history": [    {      "id": "string",      "customer_id": "string",      "customer": "string",      "kind": "commercial",      "edition": "string",      "key_id": "string",      "start": "2019-08-24T14:15:22Z",      "end": "2019-08-24T14:15:22Z",      "last_day": "2019-08-24",      "grace_days": 0,      "grace_end": "2019-08-24T14:15:22Z",      "support_until": "2019-08-24",      "limits": {        "vcpus": 0,        "users": 0,        "workspaces": 0,        "nodes": 0      },      "overage": "soft",      "installations": [        "string"      ],      "hosts": [        "string"      ],      "note": "string",      "source": "api",      "installed_at": "2019-08-24T14:15:22Z",      "installed_by_email": "string",      "standing": "active",      "problem": "string",      "test_key": true    }  ]}

The usage report for a renewal

Cluster admins only (`platform.admin`; `hart admin license usage-report`, the console's *Download usage report*). The daily highs of the counted limits since the start of the licence in force (at most a year), with the installation id, the version and the console host: counts only, no names and no email addresses. The installation never sends it anywhere; an admin hands it over at renewal.

Install a licence

Cluster admins only (`platform.admin`; `hart admin license install`). Checks the licence offline (signature, format, revocation list, the installations it names, its end) and stores it; nothing is sent anywhere. A licence whose term starts later is kept and takes over on its start date. Installing the same licence again changes nothing. Audited as `license.install`. `409` while the Helm values manage the licence (`license.existingSecret`), `422` for a licence this installation does not accept (the detail says why).