Create Role

Create a new role in the system (Admin only)

POST /api/roles

cURL

curl -X POST https://api.maqagr.com/api/roles \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "moderator",
    "description": "Moderador del sistema"
  }'

201 - Success

{
  "success": true,
  "message": "Rol creado exitosamente",
  "data": {
    "role": {
      "role_id": 3,
      "role_name": "moderator",
      "description": "Moderador del sistema",
      "status": "active",
      "created_at": "2024-03-11T20:00:00.000Z",
      "updated_at": "2024-03-11T20:00:00.000Z"
    }
  }
}

Overview

Creates a new role in the system. This endpoint is restricted to administrators only.

Admin Access Required: This endpoint requires administrator privileges. Regular users will receive a 403 Forbidden error.

Authentication

Requires JWT authentication token with admin role in the Authorization header.

Authorization: Bearer <admin_token>

Request Body

role_name · string · required

Name of the role. Must be unique and at least 2 characters long.

description · string

Description of the role and its permissions.

Response

success · boolean

Indicates if the request was successful.

message · string

Success message.

data · object

Show properties

role · object

The created role object.

Show properties

role_id · number

Unique role identifier

role_name · string

Role name

description · string

Role description

status · string

Role status (always “active” on creation)

created_at · string

Creation timestamp

updated_at · string

Last update timestamp

cURL

curl -X POST https://api.maqagr.com/api/roles \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "moderator",
    "description": "Moderador del sistema"
  }'

201 - Success

{
  "success": true,
  "message": "Rol creado exitosamente",
  "data": {
    "role": {
      "role_id": 3,
      "role_name": "moderator",
      "description": "Moderador del sistema",
      "status": "active",
      "created_at": "2024-03-11T20:00:00.000Z",
      "updated_at": "2024-03-11T20:00:00.000Z"
    }
  }
}

Validation Rules

• role_name must be provided and unique
• role_name must be at least 2 characters long
• User must have administrator role
• Role name is case-sensitive

Source Code Reference

• Route: src/routes/role.routes.js:179
• Controller: src/controllers/roleController.js:68
• Middleware: src/middleware/auth.middleware.js (isAdmin)