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

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

Path Parameters

Parameter	Type	Required	Description
userId	integer	Yes	User 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",
  "status": 3,
  "avatarUrl": "https://cdn.example.com/avatar-signed-url",
  "roles": [
    {
      "id": 1,
      "name": "Administrator"
    }
  ],
  "systemPermissions": [
    {
      "id": 10,
      "name": "system_administrator"
    }
  ]
}

Response Fields

Field	Type	Description
id	integer	User identifier
email	string	User email address
firstName	string	User first name
lastName	string	User last name
status	integer	User status value. 1 = Staged, 2 = Invited, 3 = Active, 4 = Archived
avatarUrl	string or null	Signed avatar URL when an avatar exists
roles	array	Roles assigned to the user
roles[].id	integer	Role identifier
roles[].name	string	Role display name
systemPermissions	array	System-level permissions assigned directly to the user
systemPermissions[].id	integer	Permission record identifier
systemPermissions[].name	string	Permission name

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
404 Not Found	No 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 SDK

# SDK support is in development.
# 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

• Use Get Users when you need a paged list.
• Use Update User By ID to change profile data.