Clients Domain

The Clients domain provides access to client organization details. A client is the top-level organizational unit that all other resources (users, devices, departments, apps) belong to. Every v2 endpoint is scoped under /clients/{client_id}, and this endpoint returns the client itself.

Partners are the tenant level above clients. Partner info is embedded in the Client DTO for display context but has no dedicated endpoints.

For embedding and endpoint design decisions, see the Design Guidelines.

Endpoints

Endpoint	Method	Description
Get Client	GET	Fetch the client organization by ID. Includes partner info and the active enrollment token.

Data Transfer Objects (DTOs)

Partner

Partner embedded inside Client. Partners are the tenant that owns one or more clients. No partner-specific endpoints are exposed -- this DTO exists solely for display context (e.g. showing the managing partner's name in the UI).

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "name": "TechPartner Inc."
}

Field	Type	Nullable	Description
id	string (uuid)	No	Stable unique identifier for the partner
name	string	No	Partner display name

DB source: partners.id, partners.name

Used in: Embedded inside Client.partner.

---

EnrollmentToken

The active enrollment token for a client. Enrollment tokens are used to deploy the desktop agent to devices. A client has at most one active token at a time -- generating a new token invalidates the previous one.

The value field contains the plaintext token string that users copy into the agent installer.

{
  "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
  "value": "enroll_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "description": "Default enrollment token",
  "site_id": null,
  "status": "active",
  "max_uses": null,
  "remaining_uses": null,
  "expires_at": null,
  "created_at": "2026-01-15T10:00:00.000Z"
}

Field	Type	Nullable	Description
id	string (uuid)	No	Stable unique identifier for the enrollment token
value	string	No	Plaintext token value for agent enrollment
description	string	No	Human-readable label for the token
site_id	string	Yes	Optional site identifier the token is scoped to
status	string	No	Token status: active, inactive
max_uses	integer	Yes	Maximum number of times this token can be used. null means unlimited.
remaining_uses	integer	Yes	Number of uses remaining. null means unlimited.
expires_at	string (ISO 8601)	Yes	When this token expires. null means no expiry.
created_at	string (ISO 8601)	No	When this token was generated

DB source:

DTO Field	DB Column
id	enrollment_tokens.id
value	derived from enrollment_tokens.token_hash
description	enrollment_tokens.description
site_id	enrollment_tokens.site_id
status	enrollment_tokens.status
max_uses	enrollment_tokens.max_uses
remaining_uses	enrollment_tokens.remaining_uses
expires_at	enrollment_tokens.expires_at_utc
created_at	enrollment_tokens.created_at

Omitted internal fields: client_id (in URL path), partner_id, created_by, updated_by, updated_at

Used in: Embedded inside Client.enrollment_token.

---

Client

Full client representation returned by the client detail endpoint. Embeds partner info and the active enrollment token.

{
  "id": "aa7cf840-9ca9-46a3-9778-9015d6580d50",
  "name": "Acme Corporation",
  "status": "active",
  "partner": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "TechPartner Inc."
  },
  "enrollment_token": {
    "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
    "value": "enroll_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "description": "Default enrollment token",
    "site_id": null,
    "status": "active",
    "max_uses": null,
    "remaining_uses": null,
    "expires_at": null,
    "created_at": "2026-01-15T10:00:00.000Z"
  },
  "created_at": "2025-06-01T00:00:00.000Z",
  "updated_at": "2026-02-20T12:00:00.000Z"
}

Field	Type	Nullable	Description
id	string (uuid)	No	Stable unique identifier for the client organization
name	string	No	Client organization display name
status	string	No	Client status: active
partner	Partner	No	The partner that manages this client
enrollment_token	EnrollmentToken	Yes	The active enrollment token. null if no token has been generated.
created_at	string (ISO 8601)	No	When this client record was first created
updated_at	string (ISO 8601)	No	When this client record was last modified

DB source:

DTO Field	DB Column
id	clients.id
name	clients.name
status	clients.status
partner	joined via clients.partner_id → partners
enrollment_token	joined via enrollment_tokens where client_id = ? AND status = 'active'
created_at	clients.created_at
updated_at	clients.updated_at

Omitted internal fields: partner_id (replaced by embedded partner), config (internal), created_by, updated_by

Used in: Get Client