List users | Headscale unofficial

3 parameters

idstringoptional

Filter by user identifier, provided as a uint64-formatted string.

namestringoptional

Filter users by name.

emailstringoptional

Filter users by email address.

2 status codes

200Returns an object containing a `users` array of user records, including each user's identifier, name, creation time, display name, email, provider details, and profile picture URL.

usersarray<object>required

defaultReturned when the request fails; includes a problem details object with information about the error.

detailstringoptional

A human-readable explanation specific to this occurrence of the problem.

errorsarray<object>optional

Optional list of individual error details

instancestringoptional

A URI reference that identifies the specific occurrence of the problem.

statusintegeroptional

HTTP status code

titlestringoptional

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestringoptional

A URI reference to human-readable documentation for the error.

Default:about:blank

Error handling

When supplied, id must be a uint64-formatted string. The name and email query parameters accept string values.

import { Client } from "headscale-unofficial-sdk";

const client = new Client({
  baseUrl: "https://api.acme.com",
  auth: { bearer: process.env.API_TOKEN },
});

const result = await client.user.list({
  id: "9b2f1c10-7a3e-4d54-8c2a-1f6b9e0d4a21",
  name: "Untitled",
  email: "jane.doe@example.com",
});

{
  "users": [
    {
      "createdAt": "2026-01-15T09:00:00Z",
      "displayName": "Example Name",
      "email": "user@example.com",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Example Name",
      "profilePicUrl": "https://example.com",
      "provider": "Example Academy Trust",
      "providerId": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Request

Response

Errors