Connect a Hetzner project
Projects on your device are free. Connecting a project to your team is part of Vaicoa Pro and Vaicoa Team.
The Vaicoa app 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 Vaicoa 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. Vaicoa 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’s Keychain, never sent to Vaicoa | encrypted on Vaicoa’s servers, never shown again |
| Read | by the app, while it is open | by Vaicoa 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.
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 app, 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 Vaicoa, so you do not enter it again, and the copy on your device is deleted once the transfer has worked.
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 Vaicoa. 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, Vaicoa 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 app shows 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.