Skip to main content

Get User By ID

Retrieve a single user by ID.

Authentication​

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

Endpoint​

GET /api/v1/users/{userId}
Authorization: Bearer YOUR_ACCESS_TOKEN

Request​

Headers​

HeaderRequiredDescription
AuthorizationYesBearer token for a System API client

Path Parameters​

ParameterTypeRequiredDescription
userIdintegerYesUser identifier

Query Parameters​

This endpoint does not accept query parameters.

Request Body​

This endpoint does not accept a request body.

Response​

200 OK​

Returns the requested user.

{
"id": 101,
"email": "[email protected]",
"firstName": "John",
"lastName": "Doe",
"lastLogin": "2026-04-22T10:15:30Z",
"status": 3,
"avatarUrl": "https://cdn.example.com/avatar-signed-url",
"roles": [
{
"id": 1,
"name": "Administrator"
}
],
"systemPermissions": [
{
"id": 10,
"name": "system_administrator"
}
]
}

Response Fields​

FieldTypeDescription
idintegerUser identifier
emailstringUser email address
firstNamestringUser first name
lastNamestringUser last name
lastLoginstring or nullLast login timestamp in ISO-8601 format, when available
statusintegerUser status value. 1 = Staged, 2 = Invited, 3 = Active, 4 = Archived
avatarUrlstring or nullSigned avatar URL when an avatar exists
rolesarrayRoles assigned to the user
roles[].idintegerRole identifier
roles[].namestringRole display name
systemPermissionsarraySystem-level permissions assigned directly to the user
systemPermissions[].idintegerPermission record identifier
systemPermissions[].namestringPermission name

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
404 Not FoundNo user exists with the provided userId

404 Example​

User not found

Behavior​

  • Avatar URLs are returned as signed URLs when an avatar exists
  • The roles collection includes role IDs and display names
  • The systemPermissions collection includes system-level claims assigned to the user

Example​

cURL​

curl -X GET "https://your-tenant.guardhouse.cloud/api/v1/users/101" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

.NET SDK​

using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapGet("/example/users/{userId:int}", async (int userId, IGuardhouseUsersClient usersClient) =>
{
var user = await usersClient.GetUserByIdAsync(userId);
return user is null ? Results.NotFound() : Results.Ok(user);
});

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/101",
# headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
# )

Notes​