Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TheSerchCp/SEAM-API/llms.txt

Use this file to discover all available pages before exploring further.

The POST /api/v1/sidebar/:idItem/role/:idRole endpoint creates an entry in the roleXItem pivot table, linking a sidebar navigation item to a role. Once assigned, every user whose roleId matches the given role will have that item included in the sidebarItems array returned in their login response. The endpoint validates that both the item and the role exist before inserting the assignment, and returns a conflict error if the same pair is already linked.

​
Authentication

Requires a valid JWT in the Authorization header. The authenticated user’s role must also have the permission POST /api/v1/sidebar/:idItem/role/:idRole registered in the permissions table and assigned via permissionXRole. 
Authorization: Bearer <token>

​
Request

Method: POST
Path: /api/v1/sidebar/:idItem/role/:idRole This endpoint accepts no request body — all inputs are provided as path parameters.

​
Path Parameters

​
idItem
string
required
Numeric ID of the sidebar item to assign. Must match ^\d+$. The item must already exist in the sidebarItems table. Use POST /api/v1/sidebar to create the item first if needed.
​
idRole
string
required
Numeric ID of the role to assign the item to. Must match ^\d+$. The role must already exist in the roles table.

​
Response

​
201 — Created

The item was successfully assigned to the role. The response data includes the IDs and names of both the role and the item for confirmation. 
{
  "success": true,
  "message": "Item asignado al rol exitosamente",
  "data": {
    "idRole": 2,
    "idItem": 7,
    "roleName": "Manager",
    "nameItem": "Reports"
  }
}
​
success
boolean
Always true for successful responses.
​
message
string
Human-readable confirmation: "Item asignado al rol exitosamente".
​
data
object
Confirmation object describing the assignment that was created.
​
data.idRole
integer
ID of the role the item was assigned to.
​
data.idItem
integer
ID of the sidebar item that was assigned.
​
data.roleName
string
Display name of the role sourced from the roles table (e.g. "Manager").
​
data.nameItem
string
Display label of the sidebar item sourced from the sidebarItems table (e.g. "Reports").

​
400 — Bad Request

Returned when either path parameter is not a valid numeric string. 
{
  "success": false,
  "message": "idRole must match pattern ^\\d+$"
}

​
401 — Unauthorized

Returned when the Authorization header is missing or the token is invalid/expired. 
{
  "success": false,
  "message": "Token requerido"
}

​
403 — Forbidden

Returned when the authenticated user’s role does not have the POST /api/v1/sidebar/:idItem/role/:idRole permission. 
{
  "success": false,
  "message": "No tienes permisos para acceder a este recurso"
}

​
404 — Not Found

Returned when either the specified role or the specified sidebar item does not exist. Each is validated independently by findRoleById and findItemById before the assignment is created. 
{
  "success": false,
  "message": "Rol con id 2 no encontrado"
}

{
  "success": false,
  "message": "Sidebar item con id 7 no encontrado"
}

​
409 — Conflict

Returned when the item is already assigned to the specified role. The roleXItem table is checked via SELECT 1 FROM roleXItem WHERE roleId = ? AND itemId = ? before insertion to prevent duplicates. 
{
  "success": false,
  "message": "El item ya está asignado a este rol"
}

​
Example

curl -X POST http://localhost:{PORT}/api/v1/sidebar/7/role/2 \
  -H "Authorization: Bearer <your_jwt_token>"
Once an item is assigned to a role, all users with that role will see it in their sidebar. The updated item list is reflected at the user’s next login in the sidebarItems field of the POST /api/v1/auth/login response.

​
Full Workflow

Follow these steps to create a sidebar item and make it visible to users of a specific role:
1

Create the sidebar item

Call POST /api/v1/sidebar with the item’s name, optional icon, and optional route. Note the idItem returned in the response — you will need it in step 2.
curl -X POST http://localhost:{PORT}/api/v1/sidebar \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{ "nameItem": "Reports", "iconItem": "bi bi-bar-chart", "route": "/reports" }'
2

Assign the item to the role

Call POST /api/v1/sidebar/:idItem/role/:idRole using the idItem from step 1 and the idRole of the target role. No request body is needed.
curl -X POST http://localhost:{PORT}/api/v1/sidebar/7/role/2 \
  -H "Authorization: Bearer <your_jwt_token>"
3

Verify the assignment

Log in as a user with the target role and confirm that the new item appears in the sidebarItems array of the login response.
curl -X POST http://localhost:{PORT}/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com", "password": "secret" }'

​
Real-time Events

This endpoint emits Socket.IO events throughout the assignment lifecycle:
EventStageDescription
sidebar:assignstartAssignment process initiated
sidebar:assignprocessingValidating role and item existence
sidebar:assignsuccessAssignment created, payload includes role name and item name

Build docs developers (and LLMs) love

Get started for freeTalk to us