Skip to main content

​
POST /api/roles

Creates a new role with the specified name and optional description. Roles are used to group permissions and can be assigned to users.

​
Authentication

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

​
Request Body

​
name
string
required
The name of the role. Must be unique and cannot be blank.
  • Maximum length: 100 characters
  • Example: "Administrator"
​
description
string
Optional description of the role’s purpose and responsibilities.
  • Maximum length: 200 characters
  • Example: "Full system access with all permissions"

​
Response

​
id
UUID
Unique identifier for the created role
​
name
string
The name of the role
​
description
string
The description of the role
​
permissions
array
List of permissions assigned to this role (empty for newly created roles)
​
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., blank name, exceeds length limits)
  • 409 Conflict: A role with this name already exists
  • 500 Internal Server Error: Unexpected server error

​
Example Request

curl -X POST https://api.example.com/api/roles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Administrator",
    "description": "Full system access with all permissions"
  }'

​
Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Administrator",
  "description": "Full system access with all permissions",
  "permissions": [],
  "status": "ACTIVE"
}

​
Example Error Response

{
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "abc-123-def",
  "message": "Validation failed",
  "detail": "El nombre del rol es obligatorio"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us