Connect a Hetzner project
Projects on your device are free. Connecting a project to your team is part of Pro and Team.
Cloud Viewer reads a Hetzner Cloud project through one read-only API token. Add the project on your device to see its resources and costs without an account, or connect it to your team so that Cloud Viewer keeps reading it while the app is closed, with history and alerts.
Create a read-only token
Section titled “Create a read-only token”- In the Hetzner Console, open the project.
- Go to Security → API tokens and generate a token with the permission Read.
- Copy the token. Hetzner shows it only once.
One token covers one project. Cloud Viewer only reads, so it never needs a token that can write.
On your device or connected to your team
Section titled “On your device or connected to your team”| On your device | Connected to your team | |
|---|---|---|
| Needs | nothing, no account (free mode) | Pro or Team, and the Administrator role |
| How many | any number | the plan’s limit |
| The token | in the iPhone keychain or the Android keystore, never sent to Cloud Viewer | encrypted on Cloud Viewer’s servers, never shown again |
| Read | by the app, while it is open | by Cloud Viewer every 5 minutes, also while the app is closed |
| Who sees it | this device | every member of the team |
Add a project on your device
Section titled “Add a project on your device”Settings → On This Device → Add Hetzner project. While the device has no project yet, the Dashboard also offers Add a Hetzner project. Enter a Project name, paste the token, tap Validate token, then Add. If you are signed in as a team admin, the sheet starts with Add to: leave it on This device.
Sync projects via iCloud in Settings (off by default) puts them on your other iPhones too.
On the Dashboard, tap Add a Hetzner project, or go to Settings → Projects on this device → Add Hetzner project. Enter a Project name, paste the token, tap Validate token, then Add. If you are signed in as a team admin, pick This device as the destination.
The web app has no on-device projects.
Validate token also asks Hetzner whether the token can write. If it can, the app warns “Token works, but it can WRITE” but still lets you add it. Create a read-only one instead.
Connect a project to your team
Section titled “Connect a project to your team”Only team admins can connect a project. In the apps, a member can add projects to their own device only.
- In the portal, open Hetzner Projects and click Add project.
- Enter a Project name and paste the token into Read-only API token.
- Click Connect project. The portal checks the token with Hetzner and refuses it if Hetzner rejects it or if it can write.
You can also connect a project from the app:
In the add sheet, set Add to to your team. To move a project that is already on your device, go to Settings → On This Device, swipe the project right and tap Connect. The token moves to Cloud Viewer, so you do not enter it again, and the copy on your device is deleted once the transfer has worked.
In the add sheet, pick your team as the destination. To move a project that is already on your device, add it again for your team, then remove the on-device copy.
The web app cannot add projects; use the portal.
Replace a token without losing history
Section titled “Replace a token without losing history”To rotate a token, or to fix one that stopped working:
- Create a new read-only token in the Hetzner Console.
- In the portal, open Hetzner Projects and click the key icon, Replace API token, on the project.
- Paste the token into New read-only API token and click Replace token. Syncing resumes within a minute.
- Delete the old token in the Hetzner Console.
The project keeps its id, so its cost history and events are kept. Do not disconnect and reconnect it instead: Disconnect project removes its synced data from Cloud Viewer. Only admins can replace a token, and only in the portal.
When a project’s token stops working
Section titled “When a project’s token stops working”If Hetzner refuses a connected project’s token on three syncs in a row, over about ten minutes, Cloud Viewer marks the token as revoked or invalid. This almost always means someone revoked or rotated the token in the Hetzner Console.
From then on the project no longer syncs:
- The iPhone and Android apps show Token revoked or invalid — update it in the portal on the Dashboard. The project keeps its last synced state, and its row says Token revoked or invalid.
- The portal shows “token invalid” on the Cloud projects card of the team dashboard, and a notice on Hetzner Projects that names the project.
- The team’s admins get one email about it.
To fix it, replace the token. Only admins can do this; members see “Ask a team admin to replace the token.”
When the token of a project on your device stops working, the Dashboard shows an error with Fix in Settings. Remove the project there and add it again with a new token.