The Hetzner token

Connecting a Hetzner Cloud API token is optional. You never need one to sign in, browse the dashboard, see list pricing, or run a control-plane-only hosted cluster. A token is what turns on two things: your account’s exact pricing and provisioning (worker pools and SSH keys on your own Hetzner account).

Without a token

You still see everything, at list prices. The dashboard shows Hetzner locations, machine types and prices served from kubehz’s own platform token. Because your Hetzner account may have different (for example, negotiated) pricing, these are Hetzner list prices, marked with an asterisk (*) so it is clear they are an estimate, not your bill.

You can create a hosted cluster. A control-plane-only hosted cluster needs no token: kubehz runs the control plane on its own infrastructure. A token is what lets that cluster have workers on your account, and that choice is made once, at creation: a cluster created without a connected token cannot gain worker pools later; you would connect a token and recreate it (see Worker pools). Connect one before you create the cluster if you may ever want workers on it.

With a token

Connect a token in the create wizard. You can add one to your account later (it is a tenant credential, not a per-cluster one), but worker pools are fixed at cluster creation: a cluster created without a connected token cannot gain pools later without being recreated (see Worker pools). Connecting later still gives you account-exact pricing. Which token you use decides what unlocks:

A Read & Write token unlocks provisioning. The dashboard switches from list prices to your account’s exact pricing, and you can create and scale worker pools (kubehz creates the servers on your account; you pay Hetzner directly, no kubehz markup) and manage the SSH keys used for worker nodes.

A read-only token still gives account-exact pricing. It authenticates, so prices become your account’s real figures, but provisioning stays locked, and the dashboard says so. To provision, replace it with a Read & Write token.

Create the token

In the Hetzner Cloud Console pick the project your workers should live in, then Security → API tokens → Generate API token. Choose Read & Write if you want provisioning; Read is enough for pricing alone.

How it’s validated on connect

When you connect or replace a token, kubehz checks it before storing it:

• It must authenticate: a token Hetzner refuses is rejected outright.
• It must be the right project: for a cluster that already has servers, kubehz confirms the token belongs to the same Hetzner project as those workers. A token from a different project is rejected so it can’t strand your existing nodes. (An hcloud token belongs to exactly one project. Where the check can’t run, because there are no provisioned servers yet or Hetzner is unreachable, it fails soft and stores the token.)

How it’s stored

Encrypted at rest, never echoed back. The token is encrypted before it touches our database and is used only to manage your own cluster’s resources. The dashboard never shows the value again, only whether a token is connected and when. You can replace it anytime; connecting or replacing a token requires fresh 2FA. Revoke it in the Hetzner Cloud Console whenever you like.

With the lo CLI

If you drive provisioning from lok8s, lo provision with a KUBEHZ_TOKEN (a clusters:write API token minted in the dashboard under Access → API Tokens) claims the cluster to your tenant directly. To also hand kubehz your HCLOUD_TOKEN for dashboard provisioning, opt in:

# cluster.lok8s.yaml
spec:
  kubehz:
    hosting: hosted
    connectHcloudToken: true   # send HCLOUD_TOKEN to kubehz for provisioning

This is opt-in. Without connectHcloudToken: true, your HCLOUD_TOKEN is used only locally by lo and is never sent to kubehz. Without a KUBEHZ_TOKEN, nothing is sent to kubehz at all.

Next steps

• Hosted control plane: plans and the hosted path overall.
• Worker Pools: pools, scaling and autoscaling (needs a Read & Write token).
• How it works: the trust boundary the token delegates.

---

Doc status

Aspect	Detail
State	Live: optional token; Read & Write unlocks provisioning
Last reviewed	16 July 2026