Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/RoyGeova07/Credith/llms.txt

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

The Roles API controls the permission tiers within Credith. Every user is assigned at least one role from a fixed set of three names, and that role is embedded in their JWT — governing which protected routes they may access. Roles are stored in the cd.roles table and linked to users through the cd.users_roles junction table. All role management endpoints require an authenticated session with the Owner role.
Only three role names are valid in Credith: Employee, Admin, and Owner. The API performs a case-insensitive match on the submitted name, normalizing it to the canonical casing before saving. Any other value will be rejected with a 400 error.
All role endpoints require a valid JWT token cookie and the Owner role. Requests from Admin or Employee sessions will be rejected. Deleting a role (DELETE /api/roles/:id) is a hard delete — the record is permanently removed from the database and cannot be recovered. Ensure no users depend on the role before deleting it.

​
GET /api/roles

Returns a paginated list of all roles, ordered alphabetically by name (ascending). Use limit and offset to page through results. Authentication: ✅ Required — Owner role

​
Query Parameters

​
limit
number
default:"10"
Maximum number of role records to return per page. Defaults to 10.
​
offset
number
default:"0"
Number of records to skip before collecting results. Defaults to 0.

​
Response

200 OK
​
total
number
Total count of roles in the database (before pagination).
​
data
array
Array of role objects for the current page, sorted by name ASC.
Example Response
{
  "total": 3,
  "data": [
    {
      "roleId": "11111111-aaaa-4000-8000-aaaaaaaaaaaa",
      "name": "Admin",
      "description": "Store-level administrator with full POS access"
    },
    {
      "roleId": "22222222-bbbb-4000-8000-bbbbbbbbbbbb",
      "name": "Employee",
      "description": "Standard checkout operator"
    },
    {
      "roleId": "33333333-cccc-4000-8000-cccccccccccc",
      "name": "Owner",
      "description": "Platform owner with system-wide privileges"
    }
  ]
}

​
GET /api/roles/:id

Returns a single role record by its UUID. Authentication: ✅ Required — Owner role

​
Path Parameters

​
id
string (UUID)
required
The roleId of the role to retrieve.

​
Response

200 OK — Returns the role object.
​
roleId
string (UUID)
Unique identifier for the role.
​
name
string
Role name (Employee, Admin, or Owner).
​
description
string | null
Optional description of the role.
404 Not Found 
{ "message": "Rol no encontrado" }
Example Response
{
  "roleId": "22222222-bbbb-4000-8000-bbbbbbbbbbbb",
  "name": "Employee",
  "description": "Standard checkout operator"
}

​
POST /api/roles

Creates a new role. Because only three role names are permitted system-wide and each must be unique, you can create at most three roles (one per name). Attempting to create a role with a name that already exists returns a 400 error. Authentication: ✅ Required — Owner role

​
Request Body

​
name
string
required
The role name. Must be one of Employee, Admin, or Owner (case-insensitive). The value is normalized to the canonical casing before being stored. Returns 400 if the name is invalid or already taken.
​
description
string
Optional free-text description of the role’s purpose or permissions. Stored as-is with no length enforcement.

​
Response

201 Created
​
message
string
Confirmation: "Rol creado correctamente".
​
role
object
The newly created role object, including roleId, name, and description.
Error responses:
StatusCondition
400name is missing, blank, or not one of the three accepted values
400A role with the same normalized name already exists
401Missing or invalid token cookie
403Authenticated user does not have the Owner role
500Internal server error
curl -X POST https://your-api.com/api/roles \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "name": "Admin",
    "description": "Store-level administrator with full POS access"
  }'

​
POST /api/roles/associate-user

Assigns an existing role to an existing user by inserting a row into the cd.users_roles junction table. If the user already holds the specified role, the request is rejected. A user can hold multiple roles simultaneously. Authentication: ✅ Required — Owner role

​
Request Body

​
userId
string (UUID)
required
UUID of the user (users.user_id) to assign the role to. Returns 404 if no matching user exists.
​
roleId
string (UUID)
required
UUID of the role (roles.role_id) to assign. Returns 404 if no matching role exists.

​
Response

201 Created
​
message
string
Confirmation: "Rol asociado al usuario correctamente".
​
userId
string (UUID)
The UUID of the user the role was assigned to.
​
role
object
The full role object that was associated (roleId, name, description).
Error responses:
StatusCondition
400userId or roleId is missing or blank
400The user already has the specified role assigned
401Missing or invalid token cookie
403Authenticated user does not have the Owner role
404No user found for the given userId
404No role found for the given roleId
500Internal server error
curl -X POST https://your-api.com/api/roles/associate-user \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "userId": "a1b2c3d4-0000-4000-8000-111111111111",
    "roleId": "11111111-aaaa-4000-8000-aaaaaaaaaaaa"
  }'

​
PUT /api/roles/:id

Updates the name and/or description of an existing role. Both fields are optional — only the fields present in the request body are updated. If name is provided, it must pass the same validation as POST /api/roles (must be a valid role name, and must not already be taken by a different role). Authentication: ✅ Required — Owner role

​
Path Parameters

​
id
string (UUID)
required
The roleId of the role to update.

​
Request Body

​
name
string
New role name. Must be one of Employee, Admin, or Owner (case-insensitive). Returns 400 if the name is invalid or already used by another role.
​
description
string
New description for the role. Can be set to an empty string to clear it.

​
Response

200 OK
​
message
string
Confirmation: "Rol actualizado correctamente".
​
role
object
The updated role object reflecting the new values.
Error responses:
StatusCondition
400name is provided but is not a valid role name
400name is provided but is already used by a different role
401Missing or invalid token cookie
403Authenticated user does not have the Owner role
404No role found for the given UUID
500Internal server error
cURL Example
curl -X PUT https://your-api.com/api/roles/11111111-aaaa-4000-8000-aaaaaaaaaaaa \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "description": "Administrator with access to all store reports and user management"
  }'

​
DELETE /api/roles/:id

Permanently removes a role from the database. This is a hard delete — the row is destroyed via Sequelize’s destroy() with no soft-delete fallback (paranoid is not enabled on the roles model). Any users_roles rows referencing this role will also be removed due to the ON DELETE CASCADE constraint defined on the junction table. Authentication: ✅ Required — Owner role
This action is irreversible. Once a role is deleted, all user-role associations for that role are also permanently removed via the ON DELETE CASCADE on cd.users_roles. Users who held only this role will have no roles until a new one is assigned. Verify the role is safe to remove before calling this endpoint.

​
Path Parameters

​
id
string (UUID)
required
The roleId of the role to permanently delete.

​
Response

200 OK 
{ "message": "Rol eliminado correctamente" }
Error responses:
StatusCondition
401Missing or invalid token cookie
403Authenticated user does not have the Owner role
404No role found for the given UUID
500Internal server error
cURL Example
curl -X DELETE https://your-api.com/api/roles/11111111-aaaa-4000-8000-aaaaaaaaaaaa \
  -b cookies.txt

Build docs developers (and LLMs) love

Get started for freeTalk to us