Skip to main content

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​

HeaderRequiredDescription
AuthorizationYesBearer token for a System API client

Query Parameters​

ParameterTypeRequiredDescription
pageSizeintegerNoNumber of users to return. Use a non-negative value; 0 returns an empty page.
offsetintegerNoNumber of users to skip. Negative values are normalized to 0.
emailstringNoCase-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​

FieldTypeDescription
totalintegerTotal number of matching users
usersarrayCurrent page of users
users[].idintegerUser identifier
users[].firstNamestringUser first name
users[].lastNamestringUser last name
users[].emailstringUser email address
users[].rolesarrayRoles currently assigned to the user
users[].roles[].idintegerRole identifier
users[].roles[].keystringStable role key
users[].roles[].namestringDisplay name of the role
users[].roles[].descriptionstringHuman-readable role description
users[].permissionsarrayBusiness permissions assigned directly to the user
users[].permissions[].idintegerPermission identifier
users[].permissions[].keystringStable permission key
users[].permissions[].namestringDisplay name of the permission
users[].permissions[].descriptionstringHuman-readable permission description
users[].lastLoginstring or nullLast login timestamp in ISO-8601 format, when available
users[].statusintegerUser status value. 1 = Staged, 2 = Invited, 3 = Active, 4 = Archived
users[].isSuspendedbooleanWhether the user is suspended
users[].isLockedbooleanWhether the user is currently locked
users[].avatarUrlstring or nullSigned avatar URL when an avatar exists

Errors​

StatusWhen it happens
401 UnauthorizedThe bearer token is missing, invalid, or expired
403 ForbiddenThe 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 (raw HTTP)​

# The Python beta does not expose System API helpers.
# 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​