Skip to main content

​
PUT /api/roles/

Updates the basic information (name and/or description) of an existing role. This endpoint does not modify the permissions assigned to the role.

​
Authentication

This endpoint requires authentication. Include a valid JWT token in the Authorization header.

​
Path Parameters

​
id
UUID
required
The unique identifier of the role to update

​
Request Body

​
name
string
The new name for the role. Must be unique if provided.
  • Maximum length: 100 characters
  • Example: "Super Administrator"
​
description
string
The new description for the role.
  • Maximum length: 200 characters
  • Example: "Enhanced admin role with additional privileges"

​
Response

​
id
UUID
Unique identifier of the updated role
​
name
string
The updated name of the role
​
description
string
The updated description of the role
​
permissions
array
List of permissions assigned to this role
​
id
UUID
Permission unique identifier
​
name
string
Permission name
​
description
string
Permission description
​
status
string
Permission status (ACTIVE, INACTIVE)
​
status
string
Current status of the role (ACTIVE, INACTIVE)

​
Error Responses

  • 400 Bad Request: Invalid data provided (e.g., exceeds length limits)
  • 404 Not Found: Role with the specified ID does not exist
  • 500 Internal Server Error: Unexpected server error

​
Example Request

curl -X PUT https://api.example.com/api/roles/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Super Administrator",
    "description": "Enhanced admin role with additional privileges"
  }'

​
Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Super Administrator",
  "description": "Enhanced admin role with additional privileges",
  "permissions": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "users:write",
      "description": "Permission to create and modify users",
      "status": "ACTIVE"
    }
  ],
  "status": "ACTIVE"
}

​
Example Error Response

{
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "abc-123-def",
  "message": "Role not found",
  "detail": "No role exists with ID: 550e8400-e29b-41d4-a716-446655440000"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us