Struct HeadscaleClient 

pub struct HeadscaleClient { /* private fields */ }

HTTP client for a running Headscale coordinator.

The Headscale REST API lives at <server_url>/api/v1/…. Requests are authenticated with an API key in the Authorization: Bearer <key> header. The API key must be created on the coordinator with headscale apikeys create or the equivalent API call; store it in the vault as headscale-api-key.

Implementations

impl HeadscaleClient

pub fn new( base_url: impl Into<String>, api_key: impl Into<String>, ) -> Result<Self>

Construct a client from explicit credentials.

pub fn from_vault_or_env() -> Result<Option<Self>>

Open a client from the vault (slot headscale-api-key + mesh-url) with env-var fallbacks (HEADSCALE_API_KEY + HEADSCALE_URL).

Returns Ok(None) when either credential is absent — callers can decide whether that’s fatal.

pub async fn create_preauth_key( &self, user: &str, tags: &[String], ) -> Result<PreauthKey>

Generate a single-use pre-auth key for the given ACL tags.

The key expires in 1 hour and is non-reusable — suitable for one-shot machine onboarding via cloud-init. Each yah cloud machine provision call that uses Headscale mesh should request its own key.

pub async fn list_nodes(&self) -> Result<Vec<NodeInfo>>

List all nodes currently in the tailnet.

Uses Headscale’s GET /api/v1/node (the endpoint was renamed from the pre-v0.23 /api/v1/machine, with the response key machines → nodes, when Headscale retired “machine” for “node”). The per-node JSON shape is otherwise unchanged (id, name, ipAddresses, online).

pub async fn health(&self) -> HeadscaleHealth

Light health check — HEAD or GET the Headscale root, no auth required.