API

Headscale provides a HTTP REST API which may be used to integrate a web interface, remote control Headscale or provide a base for custom integration and tooling.

The API requires a valid API key before use. To create an API key, log into your Headscale server and generate one with the default expiration of 90 days:

headscale apikeys create

Copy the output of the command and save it for later. Please note that you can not retrieve an API key again. If the API key is lost, expire the old one, and create a new one.

To list the API keys currently associated with the server:

headscale apikeys list

and to expire an API key:

headscale apikeys expire --prefix <PREFIX>

REST API

API endpoint: /api/v1, e.g. https://headscale.example.com/api/v1
Documentation: /api/v1/docs, e.g. https://headscale.example.com/api/v1/docs
Headscale Version: /version, e.g. https://headscale.example.com/version
Authenticate using HTTP Bearer authentication by sending the API key with the HTTP Authorization: Bearer <API_KEY> header.

Start by creating an API key and test it with the examples below. Read the API documentation provided by your Headscale server at /api/v1/docs for details.

=== "Get details for all users"

```console
curl -H "Authorization: Bearer <API_KEY>" \
    https://headscale.example.com/api/v1/user
```

=== "Get details for user 'bob'"

```console
curl -H "Authorization: Bearer <API_KEY>" \
    https://headscale.example.com/api/v1/user?name=bob
```

=== "Register a node"

```console
curl -H "Authorization: Bearer <API_KEY>" \
    --json '{"user": "<USER>", "authId": "<AUTH_ID>"}' \
    https://headscale.example.com/api/v1/auth/register
```

Remote control

The headscale binary can control a Headscale instance from a remote machine over the HTTP API.

Prerequisite

A workstation to run headscale (any supported platform, e.g. Linux).
The Headscale server reachable over HTTP(S).
An API key to authenticate with the Headscale server.

Setup remote control

Download the headscale binary from GitHub's release page. Make sure to use the same version as on the server.
Put the binary somewhere in your PATH, e.g. /usr/local/bin/headscale
Make headscale executable: chmod +x /usr/local/bin/headscale
Create an API key on the Headscale server.
Provide the connection parameters for the remote Headscale server either via a minimal YAML configuration file or via environment variables:

=== "Minimal YAML configuration file"
```
 ```yaml title="config.yaml"
 cli:
     address: <HEADSCALE_URL>
     api_key: <API_KEY>
 ```
```
=== "Environment variables"
```
 ```shell
 export HEADSCALE_CLI_ADDRESS="<HEADSCALE_URL>"
 export HEADSCALE_CLI_API_KEY="<API_KEY>"
 ```
```
This instructs the headscale binary to connect to a remote instance at <HEADSCALE_URL> (e.g. https://headscale.example.com), instead of connecting to the local instance. A bare host without a scheme is assumed to be https.
Test the connection by listing all nodes:
```
headscale nodes list
```
You should now be able to see a list of your nodes from your workstation, and you can now control the Headscale server from your workstation.

Behind a proxy

The remote CLI uses the same HTTP API as everything else, so it works through the reverse proxy already in front of Headscale with no extra setup.

Troubleshooting

Make sure you have the same Headscale version on your server and workstation.
Verify that your TLS certificate is valid and trusted.
If you don't have access to a trusted certificate (e.g. from Let's Encrypt), either:
- Add your self-signed certificate to the trust store of your OS or
- Disable certificate verification by either setting cli.insecure: true in the configuration file or by setting HEADSCALE_CLI_INSECURE=1 via an environment variable. We do not recommend to disable certificate validation.

4.2 KiB Raw Blame History

API