Skip to main content

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​

HeaderRequiredDescription
AuthorizationYesBearer token for a System API client
Content-TypeYesMust be application/json

Path Parameters​

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

FieldTypeRequiredDescription
keystringYesRole key. Must contain only lowercase letters and be 2 to 30 characters long.
namestringYesDisplay name of the role. Must be 3 to 100 characters long.
descriptionstringYesRole description. Can be empty, but cannot exceed 120 characters.
permissionIdsarray of integersYesComplete 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​

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 role exists with the provided roleId
409 ConflictThe 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 (raw HTTP)​

# The Python beta does not expose System API helpers.
# 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.