Connect a Hetzner project

Every cluster lives in a Hetzner Cloud project that you connect to the portal with an API token. This page connects one, explains why that project should hold nothing but your clusters, and shows how to replace its token later.

In progress: not bookable yet

Built in a lab: on 2026-10-10 the portal created clusters in a connected project on real Hetzner servers. The portal is not live, so you cannot follow these steps yet. Tell me when it opens.

Why a project of its own

A Hetzner API token opens its whole project, read and write; Hetzner offers no narrower kind. The portal needs that token to create and delete your clusters’ servers, networks, firewalls and addresses. If the project holds only your clusters, the token reaches only your clusters.

The same holds inside each cluster: its cloud controller and its volume driver use a Hetzner token of the same project. Put production in a project of its own, so that a token read in a test cluster cannot reach production’s servers.

What you need

• A Hetzner Cloud project, new or holding only servers you may want to turn into clusters.
• Membership in a team in the portal. Any member can add a project; checking and replacing its token needs a team admin.

Connect the project

1. Create the token. In the Hetzner console, open the project, go to Security → API tokens and generate a token with the permission Read & Write. Copy it.

2. Open the form. In the portal, open PaaSbox Clusters → Hetzner projects and choose Add a Hetzner project. The page Connections opens.

3. Enter the project. Under Add a connection, give the project a Project name, a label for you, and paste the token into HCLOUD_TOKEN (read/write). Choose Validate & connect.

4. Confirm what is already there, if asked. The portal checks the token against the Hetzner API, then lists what the project already holds. Servers are fine: they are candidates for adoption. Any other resource, such as a network, a firewall, a volume or a snapshot, makes the portal stop and show This project already contains resources PaaSbox did not create., with the list. Remove them in the Hetzner console and try again, or tick I acknowledge these pre-existing resources and confirm this project is dedicated to PaaSbox. and choose Validate & connect again.

The portal stores the token encrypted and says Connection added. A token Hetzner refuses gets That token could not be validated against the Hetzner API., and nothing is stored.

What you see

PaaSbox Clusters → Hetzner projects lists the project with the number of its clusters and the line Token last checked with a date. A team admin can choose Check the token at any time; the portal asks the Hetzner API with it and says whether it still works.

The portal keeps watching the project. In progress Every six hours it lists the project’s resources, and when it finds one it did not create, other than a server that was there before you connected the project, it mails the team’s admins, once per resource. It only reports: it changes, blocks and deletes nothing. A firewall or a floating IP you add yourself is such a resource.

A project PaaSbox has suspended after a security review shows suspended; you cannot create clusters in it until the suspension is lifted.

Replace the token

Replace the project’s token when it may have leaked, or on your own schedule:

1. In the Hetzner console, create a new Read & Write token in the same project.

2. If a cluster in this project was created with A copy of the project’s token, replace that copy first: its cloud controller and volume driver use it, replacing the project’s token does not change it, and revoking the old token would break them. Give the cluster a token of its own with Replace the token inside the cluster on its Settings (Rotate credentials).

3. In PaaSbox Clusters → Hetzner projects, paste the new project token under New token for this project and choose Replace. The portal checks that Hetzner accepts it and that it sees the servers of every cluster in the project; a token of another project is refused with This token does not see the servers of and the cluster’s name. If no cluster of the project has a server yet, the portal has nothing to compare: make sure yourself that the token is from the right project.

4. Only then revoke the old token in the Hetzner console.

The portal uses the new token from then on, for every cluster in the project.

Create a clusterEvery field of the form, and what the portal creates in this project.

Rotate credentialsReplace every token and key a cluster depends on.