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.

Registers a new permission in the system by recording a nameUri route pattern and its description. The roles.middleware performs a case-insensitive SQL lookup against this table on every protected request, so the nameUri you register must exactly match the HTTP method and path pattern of the route you want to guard. After a successful registration, a data:changed Socket.IO event is broadcast to all connected clients.
Valid nameUri values follow the pattern METHOD /api/v1/path, where METHOD is uppercase and the path matches the Express route exactly — including any named parameters in :param format. Examples:
  • GET /api/v1/users
  • POST /api/v1/roles
  • PUT /api/v1/roles/:idRole
  • DELETE /api/v1/users/:id
  • POST /api/v1/permission/assign
The middleware matches permissions using LOWER(nameUri) = LOWER(?), making the comparison case-insensitive in MySQL. However, the stored value should follow the UPPERCASE_METHOD /lowercase/path convention consistently to avoid confusion and duplicate entries that differ only in casing.

​
Authentication

Requires a valid JWT and the POST /api/v1/permission/register permission assigned to the caller’s role.

​
Request

Method: POST Path: /api/v1/permission/register

​
Headers

​
Authorization
string
required
Bearer token obtained from the login endpoint. Format: Bearer <token>
​
Content-Type
string
required
Must be application/json.

​
Body

​
nameUri
string
required
The route pattern to protect. Must be between 2 and 100 characters. Should follow the format METHOD /api/v1/path, e.g. DELETE /api/v1/roles/:idRole.
​
description
string
required
Human-readable description of what access this permission grants. Required (unlike the description field on roles).
Example Request Body
{
  "nameUri": "DELETE /api/v1/users/:id",
  "description": "Allows permanently deleting a user by their numeric ID"
}

​
Response

​
201 Created

Returns the newly created permission record.
​
success
boolean
Always true for successful responses.
​
message
string
Human-readable status message. Value: "Permiso registrado exitosamente".
​
data
object
The registered permission record.
Example Response
{
  "success": true,
  "message": "Permiso registrado exitosamente",
  "data": {
    "idPermission": 12,
    "nameUri": "DELETE /api/v1/users/:id",
    "description": "Allows permanently deleting a user by their numeric ID"
  }
}

​
Error Responses

StatusDescription
400 Bad RequestValidation failed — a required field is missing or nameUri is outside the 2–100 character range.
401 UnauthorizedMissing or invalid JWT token.
403 ForbiddenAuthenticated user’s role lacks the POST /api/v1/permission/register permission.
409 ConflictA permission with the same nameUri (case-insensitive) already exists.
409 Conflict
{
  "success": false,
  "message": "El permiso ya se encuentra registrado.",
  "data": null
}

​
Code Example

cURL
curl -X POST http://localhost:3000/api/v1/permission/register \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nameUri": "DELETE /api/v1/users/:id",
    "description": "Allows permanently deleting a user by their numeric ID"
  }'

​
Socket.IO Events

On success, the server emits the following events:
EventTargetOperationStatus sequence
operation:progressRequesting socketpermissions:createstart → processing → success
data:changedAll connected clientspermissions:createBroadcast with the new permission object
Clients listening to data:changed can use the initiatorSocketId field in the payload to skip redundant UI updates if they already know the result from the HTTP response.

Build docs developers (and LLMs) love

Get started for freeTalk to us