Skip to main content

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​

HeaderRequiredDescription
AuthorizationYesBearer token for a System API client

Path Parameters​

ParameterTypeRequiredDescription
permissionIdintegerYesPermission 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​

FieldTypeDescription
idintegerPermission identifier
keystringStable permission key
namestringDisplay name of the permission
descriptionstringHuman-readable permission 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
404 Not FoundNo 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 (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/1",
# headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
# )

Notes​