Update Permission By ID

Update an existing permission and replace its role assignments.

Authentication

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

Endpoint

PUT /api/v1/permissions/{permissionId}
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token for a System API client
Content-Type	Yes	Must be application/json

Path Parameters

Parameter	Type	Required	Description
permissionId	integer	Yes	Permission identifier

Query Parameters

This endpoint does not accept query parameters.

Request Body

{
  "key": "users.read",
  "name": "Users Read",
  "description": "Allows reading user records",
  "roleIds": [1, 2]
}

Request Fields

Field	Type	Required	Description
key	string	Yes	Permission key. Must be 3 to 30 characters long, use lowercase letters and dots only, and start and end with a lowercase letter.
name	string	Yes	Display name of the permission. Must be 3 to 120 characters long.
description	string	Yes	Permission description. Cannot exceed 120 characters.
roleIds	array of integers	Yes	Complete set of roles that should be associated with the permission after the update.

Validation Rules

• key is required
• key must be 3 to 30 characters long
• key can contain lowercase letters and dots only
• key must start and end with a lowercase letter
• key cannot have leading or trailing whitespace
• name is required
• name must be 3 to 120 characters long
• name cannot have leading or trailing whitespace
• description cannot exceed 120 characters
• description cannot have leading or trailing whitespace
• roleIds must contain unique values only
• The submitted key must also satisfy Guardhouse permission naming rules

Response

204 No Content

The permission was updated successfully.

This endpoint does not return a response body on success.

Errors

Status	When it happens
400 Bad Request	The request is invalid or the permission key is rejected
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
409 Conflict	Another permission already uses the submitted key

404 Example

Permission not found

409 Example

Permission with this key already exists

Behavior

• The permission metadata is updated using the submitted key, name, and description
• Existing role assignments are synchronized to the submitted roleIds
• Roles omitted from roleIds are removed from the permission
• Roles included in roleIds are assigned to the permission
• An empty roleIds array removes all current role assignments from the permission

Example

cURL

curl -X PUT "https://your-tenant.guardhouse.cloud/api/v1/permissions/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "users.read",
    "name": "Users Read",
    "description": "Allows reading user records",
    "roleIds": [1, 2]
  }'

.NET SDK

using Guardhouse.SDK.Models.Permissions;
using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapPut("/example/permissions/{permissionId:int}", async (int permissionId, IGuardhousePermissionsClient permissionsClient) =>
{
    var updated = await permissionsClient.UpdatePermissionAsync(permissionId, new UpdatePermissionRequest
    {
        Key = "users.read",
        Name = "Users Read",
        Description = "Allows reading user records",
        RoleIds = new[] { 1, 2 }
    });

    return updated ? Results.NoContent() : Results.NotFound();
});

Python SDK

# SDK support is in development.
# Use raw HTTP for now.
#
# Example shape:
# import requests
# response = requests.put(
#     "https://your-tenant.guardhouse.cloud/api/v1/permissions/1",
#     headers={
#         "Authorization": "Bearer YOUR_ACCESS_TOKEN",
#         "Content-Type": "application/json",
#     },
#     json={
#         "key": "users.read",
#         "name": "Users Read",
#         "description": "Allows reading user records",
#         "roleIds": [1, 2],
#     },
# )

Notes

• The request body represents the target state of the permission after the update.
• Use existing role IDs in roleIds.
• Use Get Permissions after updating to verify the current role assignments.