Users API Documentation

Base URL: /api/Users
Authentication: Most endpoints require a valid JWT Bearer token. Exceptions are noted per endpoint.
Header: Authorization: Bearer <token>

Table of Contents

1. Authenticate (Login)
2. Refresh Token
3. Get Group Users
4. Get Technicians
5. Get All Users
6. Search Users
7. Dual Search (Paginated)
8. Forgot Password

1. Authenticate (Login)

Validates user credentials (supports local and LDAP), issues a JWT token valid for 7 days, and records login history. The token payload includes user roles and permission claims.

Request Body (Authenticate)

Response Body (200 OK)

Token Claims

Responses

Note: Failed login attempts are recorded in login history. After a threshold of failures the account may be locked out (ASP.NET Identity lockout policy).

2. Refresh Token

Re-issues a fresh JWT token for the currently authenticated user without requiring credentials. Useful for extending a session before expiry. The new token is valid for 7 days from the time of the call.

Response Body (200 OK)

Same structure as Authenticate:

Responses

3. Get Group Users

Returns the members of a specific group (by group ID), or all technicians if no group ID is provided.

Path Parameters

Responses

4. Get Technicians

Returns all users in the Technician role.

Responses

5. Get All Users

Returns all active and visible users who are not in the Member or System roles.

Filters Applied (server-side)

• Status == Active
• IsVisible == true
• Role is not Member or System

Responses

6. Search Users

Full-text user search with optional group, department, and unassigned filters. Returns results formatted for Select2 dropdowns, including resolved avatar URLs and role lists.

Query Parameters

Search Behaviour

• With groupId: Searches within group members only; matches email OR (first name AND last name) for each keyword.
• Without groupId: Searches all active, visible non-Member/non-System users; applies department filter if departmentId is given.
• Multi-keyword search: each keyword must appear somewhere (AND logic within a field group, OR between field groups).

Response Body (200 OK)

{
  "Items": [
    {
      "Id": "string",
      "UserName": "string",
      "FullName": "string",
      "Email": "string",
      "Avatar": "https://host/path/to/avatar.jpg",
      "Roles": ["Technician", "Admin"]
    }
  ]
}

7. Dual Search (Paginated)

Paginated user search designed for dual listbox controls. Returns active, visible users who are not already assigned to the specified site. Supports multi-keyword search on email, username, first name, and last name.

Query Parameters

Response Body (200 OK)

{
  "items": [
    {
      "id": "string",
      "text": "John Doe [johndoe]"
    }
  ],
  "hasMore": true,
  "totalCount": 120,
  "page": 1,
  "pageSize": 50
}

8. Forgot Password

Sends a password reset email to the specified address if a confirmed account exists. Intentionally returns a generic success message regardless of whether the email is registered (to prevent user enumeration).

Request Body

A plain JSON string containing the email address:

"user@example.com"

Reset Link

The generated reset URL follows the pattern:

{scheme}://{host}/Identity/Account/ResetPassword?code={url-encoded-token}

Responses

Note: Email delivery failures are logged server-side but do not affect the HTTP response. The endpoint always returns 200 OK once validation passes.

Common Error Responses

Notes

• The JWT token expires 7 days after issuance. Use the Refresh Token endpoint to renew it without re-entering credentials.
• Permission claims (permission) are embedded in the token and derived from the role(s) assigned to the user. No separate permissions endpoint is needed.
• Avatar URLs returned by Search and Authenticate endpoints are fully absolute (scheme + host + path).
• User search endpoints (Search Users and Dual Search) use AND logic across keywords and OR logic between field groups (email/username vs. name).