Hetzner API Credentials

Store a Hetzner Cloud API token in Ankra - a Read & Write project token used to provision and manage Hetzner clusters.

Hetzner API credentials store a Hetzner Cloud API token, used to provision and manage Hetzner clusters. The token is validated when you save it - Ankra makes a read-only call to the Hetzner Cloud API (GET /locations), so a rejected or mistyped token is refused immediately.

Don’t have a Hetzner account? Sign up for Hetzner Cloud to get started.

What Ankra Accesses

Hetzner clusters are self-managed: Ankra provisions the servers and networking with your token, then runs Kubernetes on top. The token is used for:

Resource	Operations	Why it’s used
Servers	create, read, rescale, power actions, delete	The cluster’s nodes and bastion
SSH keys	upload, read, delete	Install your SSH key credential on the servers it creates
Private networks	create, attach, read, delete	The cluster’s private network
Load balancers and volumes	read, delete	Created by Kubernetes itself (the Hetzner cloud controller) - Ankra only cleans them up when you delete the cluster
Locations, server types, datacenters	read	Placement options and list prices in the cluster wizard

Hetzner API tokens are project-wide - there is no per-resource scoping in Hetzner’s token model, and a Read & Write token can manage everything in its project. Create the token in a project dedicated to Ankra-managed clusters if you want isolation from other workloads.

Creating a Hetzner API Credential

1. Get a Hetzner API token

   1. Log in to the Hetzner Console
   2. Select your project
   3. Go to Security → API Tokens
   4. Click Generate API Token with Read & Write permissions - a read-only token passes the save-time check but fails as soon as Ankra needs to create a server
   5. Copy the token (it’s only shown once)
2. Add to Ankra (UI)

   Go to Credentials → Add → Hetzner, then provide:

   • Name: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. hetzner-prod)
   • API Token: the token from the previous step

   Click Test connection to verify the token against the Hetzner API, then save.

3. Or via CLI

   ankra credentials hetzner create --name my-hetzner-token
   # You will be securely prompted for the API token
   

For self-managed Hetzner clusters you also need an SSH key credential.

The token can be rotated later from the credential’s page without recreating the credential - everything using it picks up the new token automatically.

Listing Hetzner Credentials

CLI

ankra credentials hetzner list

Troubleshooting Hetzner Credentials

The table below covers the Test connection result in the Ankra UI:

Test connection result	Cause	Solution
Hetzner rejected the API token.	The token is invalid, revoked, or was copied incompletely	Generate a new token and paste the full value
Hetzner accepted the token but denied the request.	The token lacks access to the project’s resources	Generate a Read & Write token for the right project
Could not reach the Hetzner Cloud API.	Network or connectivity issue	Retry; ensure outbound access to api.hetzner.cloud
Hetzner returned HTTP <code>.	Unexpected Hetzner-side response	Retry; check the Hetzner status page if it persists

Test connection verifies the token is accepted, not that it can write. If the credential saves fine but cluster provisioning later fails with a permissions error, the token is read-only - generate a Read & Write token and rotate it in on the credential’s page.