Update Role By ID

Update an existing role and replace its assigned permissions.

Authentication

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

Endpoint

PUT /api/v1/roles/{roleId}
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
roleId	integer	Yes	Role identifier. Must be greater than 0.

Query Parameters

This endpoint does not accept query parameters.

Request Body

{
  "key": "administrator",
  "name": "Administrator",
  "description": "Full administrative access",
  "permissionIds": [1, 2, 3]
}

Request Fields

Field	Type	Required	Description
key	string	Yes	Role key. Must contain only lowercase letters and be 2 to 30 characters long.
name	string	Yes	Display name of the role. Must be 3 to 100 characters long.
description	string	Yes	Role description. Can be empty, but cannot exceed 120 characters.
permissionIds	array of integers	Yes	Complete set of permission IDs that should be assigned to the role after the update.

Validation Rules

• roleId must be a positive integer
• key is required
• key must be 2 to 30 characters long
• key can contain lowercase letters only: a-z
• key cannot have leading or trailing whitespace
• name is required
• name must be 3 to 100 characters long
• name cannot have leading or trailing whitespace
• description cannot exceed 120 characters
• description cannot have leading or trailing whitespace
• permissionIds must contain unique values only

Response

204 No Content

The role was updated successfully.

This endpoint does not return a response body on success.

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 role exists with the provided roleId
409 Conflict	The submitted data conflicts with an existing role or contains invalid permission IDs

404 Example

Role not found.

409 Examples

Duplicate role name:

Role with name 'Administrator' already exists.

Duplicate role key:

Role with key 'administrator' already exists.

Invalid permission IDs:

One or more permission IDs are invalid.

Behavior

• The role metadata is updated using the provided key, name, and description
• Existing role permissions are recalculated from the submitted permissionIds
• Permission IDs not included in the request are removed from the role
• Permission IDs included in the request are assigned to the role
• An empty permissionIds array removes all currently assigned permissions from the role

Example

cURL

curl -X PUT "https://your-tenant.guardhouse.cloud/api/v1/roles/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "administrator",
    "name": "Administrator",
    "description": "Full administrative access",
    "permissionIds": [1, 2, 3]
  }'

.NET SDK

using Guardhouse.SDK.Models.Roles;
using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapPut("/example/roles/{roleId:int}", async (int roleId, IGuardhouseRolesClient rolesClient) =>
{
    var updated = await rolesClient.UpdateRoleAsync(roleId, new UpdateRoleRequest
    {
        Key = "administrator",
        Name = "Administrator",
        Description = "Full administrative access",
        PermissionIds = new[] { 1, 2, 3 }
    });

    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/roles/1",
#     headers={
#         "Authorization": "Bearer YOUR_ACCESS_TOKEN",
#         "Content-Type": "application/json",
#     },
#     json={
#         "key": "administrator",
#         "name": "Administrator",
#         "description": "Full administrative access",
#         "permissionIds": [1, 2, 3],
#     },
# )

Notes

• The request body represents the target state of the role after the update.
• permissionIds should contain the complete set of permissions you want the role to have.
• Use Get Role By ID after updating to verify the final permission matrix.
• Use Getting Access Credentials if you still need to configure a System API client or obtain a token.