Connect your Hetzner project

Adding a Hetzner Cloud project links your infrastructure to CloudTally using a read-only API token generated in the Hetzner Cloud Console. Once connected, CloudTally reviews your project resources, applies current pricing, and presents your month-to-date spending on the dashboard.

CloudTally requires a read-only token. After token validation, it only reads resource counts and configurations; it does not use the token to modify, resize, reboot, or delete your servers, volumes, networks, or other provider resources. If a token containing write permissions is supplied, CloudTally rejects it.

Prerequisites

Before connecting a project in CloudTally, ensure you have:

• An active Hetzner account with access to the Hetzner Cloud Console.
• At least one Hetzner Cloud project containing resources you want to track.
• An account in CloudTally with Owner or Admin permissions in your organisation.

Step 1: Generate a read-only API token in Hetzner

CloudTally authenticates against the Hetzner Cloud API using a token scoped to your project. Generate this token in the Hetzner Cloud Console:

1. Sign in to the Hetzner Cloud Console.
2. Select the project you want to track in CloudTally.
3. In the project sidebar, select Security, then choose API Tokens.
4. Click Generate API Token.
5. Enter a token description, such as cloudtally-readonly.
6. Under Permissions, select Read only. Do not select Read & Write. CloudTally rejects tokens with write permissions.
7. Click Generate API Token.
8. Copy the 64-character token string. Hetzner displays this token only once upon creation.

For additional information on token creation, consult the Hetzner API token documentation and Hetzner API overview.

Step 2: Add the project in CloudTally

Once you have generated your token, add the connection in CloudTally:

1. Open CloudTally and select Settings in the navigation menu.
2. Select Projects.
3. Click Add project. (If your organisation has no connected projects, you can also select Add project from the initial empty state on the Dashboard).
4. Complete the required form fields:
   • Project Name: Enter a label your team will recognise, such as Production Europe.
   • Hetzner API Token: Paste the 64-character token copied from the Hetzner Cloud Console.
5. Optional: Open your project in the Hetzner Cloud Console, copy its address, and paste it into Hetzner Console project. You can also enter the project ID. This adds an Open in Hetzner Console link to recommendations and Cost Explorer resource details.
6. Click Add project.

Token validation and error handling

CloudTally verifies the token against the Hetzner Cloud API when you submit the form. If validation does not succeed, CloudTally displays a specific message:

CloudTally verifies that your token is read-only before saving it. This one-time permission check does not create or modify resources in your Hetzner project, and tokens with write permissions are rejected.

• API token must be a 64-character alphanumeric string.: The pasted value does not match the required token format. Ensure there are no extra spaces or missing characters.
• Use a read-only Hetzner API token for this project: The provided token has write permissions. Generate a new token in the Hetzner Cloud Console with permissions set strictly to Read.
• Invalid Hetzner API token. Please check the token and try again.: The token was rejected by Hetzner. Verify that the token is active in the Hetzner Cloud Console.
• A project with this name already exists in your organisation.: Another project in your organisation is already using this display name. Choose a different name in the Project Name field.
• This Hetzner project is already connected to your organisation.: A connection matching this project's identifier already exists in your organisation.
• This project was previously connected to your organisation. Reactivate it to resume tracking.: This project was previously disconnected. Select Reactivate to restore it and reconnect historical data.
• Unable to reach Hetzner Cloud API. Please try again in a few moments.: CloudTally could not reach Hetzner endpoints. Check connection status and retry.

Step 3: Waiting room and history treatment

When the token passes validation, the dialog transitions to the waiting room:

1. The dialog shows the title Connected along with Syncing your history... and the description: You can close this window. The dashboard banner will appear when setup is ready. You can keep the modal open or close it; CloudTally completes the history review in the background.
2. When the spending review is prepared, the modal updates to History ready with the description: Choose how CloudTally should treat reconstructed month-to-date spend.
3. Click Set it up to select how reconstructed history should be handled. You are presented with three options:
   • Adopt: Count confident reconstructed spend in budgets, charts, and forecasts.
   • Display only: Show reconstructed spend with labels, but keep it out of budgets.
   • Start fresh: Ignore reconstructed spend and track only observed cost from now on.
4. When an organisation default or recommended setting is configured, CloudTally applies that choice automatically. You can select Review coverage to inspect data coverage details.
5. If you closed the dialog earlier, a banner on the dashboard alerts you when history setup is ready so you can complete or review the decision.

Step 4: Open your dashboard

When the connection and any required history setup are ready, navigate to the Dashboard. The previous No cost data yet empty state updates with your latest synced data:

• This month: Current month-to-date accrued cost in your organisation's display currency, usually EUR or USD. CloudTally sets this from the first connected project's pricing data; you can view it, but not change it, under Settings → General → Display currency.
• Projected month-end: Estimated total spend at the end of the month based on current resource run rates.
• Budget: Spending progress relative to active budget targets.
• Spend trends and cost distribution charts.

What to do next

• Manage update schedules and credentials: Use the project Actions menu to review history coverage, rotate a token or pause updates.
• Interpret dashboard metrics: Learn about smart forecasts, billing caps, and spend trend events in Understand your CloudTally dashboard.