Get Permission By ID

Retrieve a single permission by its ID.

Authentication

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

Endpoint

GET /api/v1/permissions/{permissionId}
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
permissionId	integer	Yes	Permission 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 permission.

{
  "id": 1,
  "key": "users.read",
  "name": "Users Read",
  "description": "Allows reading user records"
}

Response Fields

Field	Type	Description
id	integer	Permission identifier
key	string	Stable permission key
name	string	Display name of the permission
description	string	Human-readable permission 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
404 Not Found	No permission exists with the provided permissionId

404 Example

Permission not found

Example

cURL

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

.NET SDK

using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapGet("/example/permissions/{permissionId:int}", async (int permissionId, IGuardhousePermissionsClient permissionsClient) =>
{
    var permission = await permissionsClient.GetPermissionByIdAsync(permissionId);
    return permission is null ? Results.NotFound() : Results.Ok(permission);
});

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

Notes

• Use Get Permissions when you need the full permission list with associated roles.
• Use Getting Access Credentials if you still need to configure a System API client or obtain a token.