Skip to main content

​
Overview

The Roles API allows you to manage user roles in the Blog Marketing Platform. The system includes 6 predefined roles with different permission levels, and you can create custom roles to fit your organization’s needs.

​
Available Roles

The platform includes the following predefined roles:

Creador

Complete system access with all permissions

Administrador

System management and configuration capabilities

Editor

Content editing and moderation permissions

Escritor

Content creation and drafting capabilities

Autor

Post publishing and authoring permissions

Comentador

Basic commenting and interaction permissions

​
Get All Roles

Function Reference: getAllRoles() - rbacService.ts:31
Retrieves a list of all available roles in the system.

​
Request

GET /api/rbac/roles

​
Response

Returns an array of role objects.
​
roles
Rol[]
Array of role objects

​
Example

import { getAllRoles } from './services/rbacService';

const roles = await getAllRoles();
console.log(roles);
// [
//   { id: 1, nombre: 'Creador', descripcion: 'Acceso completo' },
//   { id: 2, nombre: 'Administrador', descripcion: 'Gestión del sistema' },
//   ...
// ]

​
Create Role

Function Reference: createRol(data) - rbacService.ts:55
Creates a new custom role in the system.

​
Request

POST /api/rbac/roles

​
Parameters

​
nombre
string
required
Name of the role. Should be descriptive and unique.
​
descripcion
string
Optional description explaining the role’s purpose and permissions.

​
Response

Returns the created role object or null if creation fails.
​
role
Rol | null
The newly created role object with all fields populated

​
Example

import { createRol } from './services/rbacService';

const newRole = await createRol({
  nombre: 'Moderador',
  descripcion: 'Puede moderar contenido y usuarios'
});

if (newRole) {
  console.log('Role created:', newRole);
  // { id: 7, nombre: 'Moderador', descripcion: '...' }
}
Ensure the role name is unique. Duplicate role names may cause conflicts in permission management.

​
Delete Role

Function Reference: deleteRol(id) - rbacService.ts:83
Deletes a single role by its ID.

​
Request

DELETE /api/rbac/roles/:id

​
Parameters

​
id
number
required
The unique identifier of the role to delete

​
Response

Returns a boolean indicating success or failure.
​
success
boolean
true if the role was successfully deleted, false otherwise

​
Example

import { deleteRol } from './services/rbacService';

const roleId = 7;
const success = await deleteRol(roleId);

if (success) {
  console.log('Role deleted successfully');
} else {
  console.error('Failed to delete role');
}
Deleting a role that is currently assigned to users may cause permission issues. Ensure users are reassigned to different roles before deletion.

​
Delete Multiple Roles

Function Reference: deleteRoles(ids) - rbacService.ts:98
Deletes multiple roles in a single operation using their IDs.

​
Request

DELETE /api/rbac/roles

​
Parameters

​
ids
number[]
required
Array of role IDs to delete. Each ID must correspond to an existing role.

​
Response

Returns a boolean indicating whether all deletions succeeded.
​
success
boolean
true if all roles were successfully deleted, false if any deletion failed

​
Example

import { deleteRoles } from './services/rbacService';

const roleIds = [7, 8, 9];
const success = await deleteRoles(roleIds);

if (success) {
  console.log('All roles deleted successfully');
} else {
  console.error('Failed to delete some or all roles');
}

​
Type Definitions

​
Rol Interface

interface Rol {
  id: number;              // Unique role identifier
  nombre: string;          // Role name
  descripcion?: string;    // Optional role description
  created_at?: string;     // ISO 8601 creation timestamp
  updated_at?: string;     // ISO 8601 last update timestamp
}

​
RolConPermisos Interface

interface RolConPermisos extends Rol {
  permisos: Permiso[];     // Array of permissions assigned to this role
}

​
Role Types

The types.ts file defines the following role type: 
type Role = 'creador' | 'administrador' | 'editor' | 'escritor' | 'autor' | 'comentador';

​
Best Practices

  • Use descriptive names that clearly indicate the role’s purpose
  • Follow consistent naming patterns (e.g., Spanish or English, not mixed)
  • Avoid special characters in role names
  • Keep names concise but meaningful
  • Always verify role assignments before deletion
  • Use the RolConPermisos interface when working with roles and their permissions together
  • Document custom roles and their intended permissions
  • Regularly audit role assignments for security compliance
  • Always check for null returns from create operations
  • Verify boolean success responses before proceeding with dependent operations
  • Implement proper error logging for failed role operations
  • Handle edge cases like duplicate role names gracefully

Permissions API

Manage permissions and assign them to roles

User Management

Assign roles to users and manage user permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us