The Hetzner token

A Hetzner Cloud API token is optional. You never need one to sign in, to browse the dashboard, to see list prices, or to run a control-plane-only hosted cluster. A token 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. kubehz reads them with its own platform token. Your Hetzner account can have different prices (for example, negotiated prices). So the dashboard shows Hetzner list prices and marks them with an asterisk (*): they are an estimate, not your bill.

You can create a hosted cluster. A control-plane-only hosted cluster needs no token, because kubehz runs the control plane on its own infrastructure. A token lets that cluster have workers on your account, and you make that choice once, at creation.

A cluster created without a connected token cannot gain worker pools later. To get workers, you connect a token and recreate the cluster (see Worker pools). If you may ever want workers on the cluster, connect a token before you create it.

With a token

Connect a token in the create wizard. You can also add a token to your account later, because it is a tenant credential, not a per-cluster credential. But you choose worker pools at cluster creation: a cluster created without a connected token cannot gain worker pools later unless you recreate it (see Worker pools). A token that you connect later still gives you account-exact pricing. The type of token decides what it turns on:

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

A read-only token still gives account-exact pricing. The token authenticates, so the prices become the real figures of your account. But provisioning stays locked, and the dashboard tells you so. To provision, replace the token with a Read & Write token.

Create the token

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

How kubehz checks the token

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

• The token must authenticate. kubehz rejects a token that Hetzner refuses.
• The token must belong to the right project. For a cluster that already has servers, kubehz confirms that the token belongs to the same Hetzner project as those workers. kubehz rejects a token from a different project, so that the token cannot strand your existing nodes. (An hcloud token belongs to exactly one project.) Sometimes the check cannot run: there are no provisioned servers yet, or Hetzner is unreachable. Then the check fails soft, and kubehz stores the token.

How kubehz stores the token

Encrypted at rest, never shown again. kubehz encrypts the token before the token reaches our database. kubehz uses the token only to manage the resources of your own cluster. The dashboard never shows the value again. It shows only whether a token is connected, and since when.

You can replace the token at any time. To connect or replace a token, you need a fresh 2FA check. You can revoke the token in the Hetzner Cloud Console whenever you like.

With the lo CLI

If you provision with lok8s, lo provision with a KUBEHZ_TOKEN claims the cluster to your tenant directly. A KUBEHZ_TOKEN is a clusters:write API token that you create in the dashboard under Access → API Tokens. To also give 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, lo uses your HCLOUD_TOKEN only locally and never sends it to kubehz. Without a KUBEHZ_TOKEN, lo sends nothing to kubehz at all.

Next steps

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

---

Doc status

Aspect	Detail
State	Live: optional token, Read & Write turns on provisioning
Last reviewed	30 October 2026