Skip to main content

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​

HeaderRequiredDescription
AuthorizationYesBearer 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​

FieldTypeDescription
itemsarrayList of roles
items[].idintegerRole identifier
items[].keystringStable role key
items[].namestringDisplay name of the role
items[].descriptionstringHuman-readable role description
items[].permissionsarrayFull list of permissions with assignment state for this role
items[].permissions[].idintegerPermission identifier
items[].permissions[].namestringPermission name
items[].permissions[].isActivebooleantrue when the permission is assigned to the role

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

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 (raw HTTP)​

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