Get Role By ID

Retrieve a single role by its ID, including the permission matrix for that role.

Authentication

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

Endpoint

GET /api/v1/roles/{roleId}
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
roleId	integer	Yes	Role identifier. Must be greater than 0.

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 role. The permissions collection includes the full permission list, and isActive shows whether each permission is assigned to the role.

{
  "id": 1,
  "key": "administrator",
  "name": "Administrator",
  "description": "Full administrative access",
  "permissions": [
    {
      "id": 1,
      "name": "users.read",
      "isActive": true
    },
    {
      "id": 2,
      "name": "users.write",
      "isActive": true
    },
    {
      "id": 3,
      "name": "roles.manage",
      "isActive": true
    }
  ]
}

Response Fields

Field	Type	Description
id	integer	Role identifier
key	string	Stable role key
name	string	Display name of the role
description	string	Human-readable role description
permissions	array	Full list of permissions with assignment state for this role
permissions[].id	integer	Permission identifier
permissions[].name	string	Permission name
permissions[].isActive	boolean	true when the permission is assigned to the role

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 role exists with the provided roleId

404 Example

Role not found

Example

cURL

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

.NET SDK

using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapGet("/example/roles/{roleId:int}", async (int roleId, IGuardhouseRolesClient rolesClient) =>
{
    var role = await rolesClient.GetRoleByIdAsync(roleId);
    return role is null ? Results.NotFound() : Results.Ok(role);
});

Python SDK

# SDK support is in development.
# Use raw HTTP for now.
#
# Example shape:
# import requests
# response = requests.get(
#     "https://your-tenant.guardhouse.cloud/api/v1/roles/1",
#     headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
# )

Notes

• roleId must be a positive integer.
• This endpoint returns the full permission list for the role, not only active permissions.
• Use Getting Access Credentials if you still need to configure a System API client or obtain a token.