Get Users

Retrieve a paged list of users, with optional email search.

Authentication

This endpoint requires a bearer access token for the System API.

Endpoint

GET /api/v1/users
Authorization: Bearer YOUR_ACCESS_TOKEN

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token for a System API client

Query Parameters

Parameter	Type	Required	Description
pageSize	integer	No	Number of users to return. Negative values are normalized to 0.
offset	integer	No	Number of users to skip. Negative values are normalized to 0.
email	string	No	Case-insensitive partial email search filter.

Request Body

This endpoint does not accept a request body.

Response

200 OK

Returns the total number of matching users and the current result set.

{
  "total": 2,
  "users": [
    {
      "id": 101,
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "roles": [
        {
          "id": 1,
          "key": "administrator",
          "name": "Administrator",
          "description": "Full administrative access"
        }
      ],
      "permissions": [
        {
          "id": 1,
          "key": "users.read",
          "name": "Users Read",
          "description": "Allows reading user records"
        }
      ],
      "lastLogin": "2026-04-22T10:15:30Z",
      "status": 3,
      "isSuspended": false,
      "isLocked": false,
      "avatarUrl": "https://cdn.example.com/avatar-signed-url"
    }
  ]
}

Response Fields

Field	Type	Description
total	integer	Total number of matching users
users	array	Current page of users
users[].id	integer	User identifier
users[].firstName	string	User first name
users[].lastName	string	User last name
users[].email	string	User email address
users[].roles	array	Roles currently assigned to the user
users[].roles[].id	integer	Role identifier
users[].roles[].key	string	Stable role key
users[].roles[].name	string	Display name of the role
users[].roles[].description	string	Human-readable role description
users[].permissions	array	Business permissions assigned directly to the user
users[].permissions[].id	integer	Permission identifier
users[].permissions[].key	string	Stable permission key
users[].permissions[].name	string	Display name of the permission
users[].permissions[].description	string	Human-readable permission description
users[].lastLogin	string or null	Last login timestamp in ISO-8601 format, when available
users[].status	integer	User status value. 1 = Staged, 2 = Invited, 3 = Active, 4 = Archived
users[].isSuspended	boolean	Whether the user is suspended
users[].isLocked	boolean	Whether the user is currently locked
users[].avatarUrl	string or null	Signed avatar URL when an avatar exists

Errors

Status	When it happens
401 Unauthorized	The bearer token is missing, invalid, or expired
403 Forbidden	The token is valid but does not have access to this endpoint

Behavior

• Results are ordered by user ID ascending
• email filtering uses case-insensitive partial matching
• Avatar URLs are returned as signed URLs when an avatar exists

Example

cURL

curl -X GET "https://your-tenant.guardhouse.cloud/api/v1/users?pageSize=20&offset=0&email=john" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

.NET SDK

using Guardhouse.SDK.Models.Users;
using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapGet("/example/users", async (IGuardhouseUsersClient usersClient) =>
{
    var users = await usersClient.GetUsersAsync(new GetUsersRequest
    {
        PageSize = 20,
        Offset = 0,
        Email = "john"
    });

    return Results.Ok(users);
});

Python SDK

# SDK support is in development.
# Use raw HTTP for now.
#
# Example shape:
# response = requests.get(
#     "https://your-tenant.guardhouse.cloud/api/v1/users",
#     headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
#     params={"pageSize": 20, "offset": 0, "email": "john"},
# )

Notes

• Use Get User By ID when you need a single user record.
• Use Block User By ID and Unblock User By ID for suspension management.