Get Roles

Retrieve all roles available in Guardhouse, including the permission matrix for each role.

Authentication

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

Endpoint

GET /api/v1/roles
Authorization: Bearer YOUR_ACCESS_TOKEN

Request

Headers

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

Query Parameters

This endpoint does not accept query parameters.

Request Body

This endpoint does not accept a request body.

Response

200 OK

Returns all roles. Each role includes its basic metadata and the full permission list. The isActive flag shows whether a permission is assigned to that role.

{
  "items": [
    {
      "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
        }
      ]
    },
    {
      "id": 2,
      "key": "viewer",
      "name": "Viewer",
      "description": "Read-only access",
      "permissions": [
        {
          "id": 1,
          "name": "users.read",
          "isActive": true
        },
        {
          "id": 2,
          "name": "users.write",
          "isActive": false
        },
        {
          "id": 3,
          "name": "roles.manage",
          "isActive": false
        }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
items	array	List of roles
items[].id	integer	Role identifier
items[].key	string	Stable role key
items[].name	string	Display name of the role
items[].description	string	Human-readable role description
items[].permissions	array	Full list of permissions with assignment state for this role
items[].permissions[].id	integer	Permission identifier
items[].permissions[].name	string	Permission name
items[].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

Example

cURL

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

.NET SDK

using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapGet("/example/roles", async (IGuardhouseRolesClient rolesClient) =>
{
    var roles = await rolesClient.GetRolesAsync();
    return Results.Ok(roles);
});

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

Notes

• This endpoint returns all roles in a single response.
• Each returned role contains the full permission list, not only the active permissions.
• Use Getting Access Credentials if you still need to configure a System API client or obtain a token.