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

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 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

Field	Type	Description
items	array	List of permissions
items[].id	integer	Permission identifier
items[].key	string	Stable permission key
items[].name	string	Display name of the permission
items[].description	string	Human-readable permission description
items[].roles	array	Roles currently associated with the permission
items[].roles[].id	integer	Role identifier
items[].roles[].key	string	Stable role key
items[].roles[].name	string	Display name of the role
items[].roles[].description	string	Human-readable role description

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/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 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/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.