Skip to main content

Get Permissions

Retrieve all permissions available in Guardhouse, including the roles currently associated with each permission.

Authentication​

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

Endpoint​

GET /api/v1/permissions
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 permissions. Each permission includes its metadata and the list of roles that currently include that permission.

{
"items": [
{
"id": 1,
"key": "users.read",
"name": "Users Read",
"description": "Allows reading user records",
"roles": [
{
"id": 1,
"key": "administrator",
"name": "Administrator",
"description": "Full administrative access"
},
{
"id": 2,
"key": "viewer",
"name": "Viewer",
"description": "Read-only access"
}
]
},
{
"id": 2,
"key": "users.write",
"name": "Users Write",
"description": "Allows changing user records",
"roles": [
{
"id": 1,
"key": "administrator",
"name": "Administrator",
"description": "Full administrative access"
}
]
}
]
}

Response Fields​

FieldTypeDescription
itemsarrayList of permissions
items[].idintegerPermission identifier
items[].keystringStable permission key
items[].namestringDisplay name of the permission
items[].descriptionstringHuman-readable permission description
items[].rolesarrayRoles currently associated with the permission
items[].roles[].idintegerRole identifier
items[].roles[].keystringStable role key
items[].roles[].namestringDisplay name of the role
items[].roles[].descriptionstringHuman-readable role description

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/permissions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

.NET SDK​

using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapGet("/example/permissions", async (IGuardhousePermissionsClient permissionsClient) =>
{
var permissions = await permissionsClient.GetPermissionsAsync();
return Results.Ok(permissions);
});

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

Notes​

  • Permissions are returned as a flat list.
  • Each permission includes the roles currently linked to it.
  • Use Get Permission By ID when you need a single permission record.