Permissions Management - Blog Marketing Platform

Overview

The Permissions API enables fine-grained access control by managing permissions and their assignments to roles. The system includes 12 predefined permission types covering all major platform features.

Permission Types

The following permissions are available in the system (defined in types.ts:11):

admin_completo

Full administrative access to all platform features

asignar_roles

Ability to assign and modify user roles

comentar

Permission to create comments on posts

crear_categoria

Create new content categories

crear_post

Create new blog posts and drafts

editar_categoria

Edit existing category information

editar_post_cualquiera

Edit any post in the system (not just own posts)

editar_post_propio

Edit only posts authored by the user

eliminar_categoria

Delete categories from the system

publicar_post

Publish posts to make them publicly visible

reaccionar

React to posts and comments (likes, etc.)

rechazar_post

Reject submitted posts during moderation

Get All Permissions

Function Reference: getAllPermisos() - rbacService.ts:117

Retrieves a complete list of all available permissions in the system.

Request

GET /api/rbac/permissions

Response

Returns an array of permission objects.

permissions

Permiso[]

Array of permission objects

Show Permiso object properties

number

required

Unique identifier for the permission

nombre

string

required

Permission name (e.g., “crear_post”, “editar_post_cualquiera”)

descripcion

string

Human-readable description of what the permission grants

created_at

string

ISO 8601 timestamp of permission creation

updated_at

string

ISO 8601 timestamp of last permission update

Example

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

const permissions = await getAllPermisos();
console.log(permissions);
// [
//   { id: 1, nombre: 'crear_post', descripcion: 'Crear posts' },
//   { id: 2, nombre: 'editar_post', descripcion: 'Editar posts' },
//   { id: 3, nombre: 'eliminar_post', descripcion: 'Eliminar posts' },
//   ...
// ]

Create Permission

Function Reference: createPermiso(data) - rbacService.ts:144

Creates a new custom permission that can be assigned to roles.

Request

POST /api/rbac/permissions

Parameters

nombre

string

required

Name of the permission. Use snake_case convention (e.g., “export_analytics”).

descripcion

string

Optional description explaining what the permission grants access to.

Response

Returns the created permission object or null if creation fails.

permission

Permiso | null

The newly created permission object with all fields populated

Show Properties

number

Auto-generated unique identifier

nombre

string

The permission name provided in the request

descripcion

string

The permission description if provided

created_at

string

ISO 8601 timestamp of creation

updated_at

string

ISO 8601 timestamp of last update

Example

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

const newPermission = await createPermiso({
  nombre: 'export_analytics',
  descripcion: 'Exportar datos de analytics'
});

if (newPermission) {
  console.log('Permission created:', newPermission);
}

Delete Permission

Function Reference: deletePermiso(id) - rbacService.ts:172

Deletes a single permission by its ID.

Request

DELETE /api/rbac/permissions/:id

Parameters

number

required

The unique identifier of the permission to delete

Response

success

boolean

true if the permission was successfully deleted, false otherwise

Example

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

const success = await deletePermiso(8);

if (success) {
  console.log('Permission deleted successfully');
}

Deleting a permission that is assigned to roles will remove it from all those roles. This may affect user access immediately.

Delete Multiple Permissions

Function Reference: deletePermisos(ids) - rbacService.ts:187

Deletes multiple permissions in a single batch operation.

Request

DELETE /api/rbac/permissions

Parameters

ids

number[]

required

Array of permission IDs to delete

Response

success

boolean

true if all permissions were deleted successfully, false otherwise

Example

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

const success = await deletePermisos([8, 9, 10]);

if (success) {
  console.log('All permissions deleted');
}

Get Permissions by Role

Function Reference: getPermisosByRole() - rbacService.ts:206

Retrieves a mapping of all roles to their assigned permissions.

Request

GET /api/rbac/permissions/by-role

Response

Returns an object where keys are role IDs and values contain role information with their permissions.

rolesMap

Record<number, RolConPermisos>

Object mapping role IDs to role data with permissions

Show Structure

[roleId]

RolConPermisos

Role object with permissions array

Show Properties

number

Role ID

nombre

string

Role name

descripcion

string

Role description

permisos

Permiso[]

Array of permission objects assigned to this role

Example

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

const rolesWithPermisos = await getPermisosByRole();

// Access permissions for role ID 1
if (rolesWithPermisos[1]) {
  console.log('Role:', rolesWithPermisos[1].nombre);
  console.log('Permissions:', rolesWithPermisos[1].permisos);
}

Assign Permission to Role

Function Reference: assignPermisoToRole(rolId, permisoId) - rbacService.ts:223

Assigns a specific permission to a role, granting that capability to all users with that role.

Request

POST /api/rbac/roles/:rolId/permissions

Parameters

rolId

number

required

The ID of the role to assign the permission to

permisoId

number

required

The ID of the permission to assign

Response

success

boolean

true if the permission was successfully assigned, false otherwise

Example

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

const rolId = 4; // Escritor role
const permisoId = 4; // publicar_post permission

const success = await assignPermisoToRole(rolId, permisoId);

if (success) {
  console.log('Permission assigned successfully');
  // All users with "Escritor" role can now publish posts
}

Permission assignments take effect immediately for all users with the specified role.

Revoke Permission from Role

Function Reference: revokePermisoFromRole(roleId, permisoId) - rbacService.ts:244

Removes a specific permission from a role.

Request

DELETE /api/rbac/roles/:roleId/permissions/:permisoId

Parameters

roleId

number

required

The ID of the role to revoke the permission from

permisoId

number

required

The ID of the permission to revoke

Response

success

boolean

true if the permission was successfully revoked, false otherwise

Example

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

const roleId = 6; // Comentador role
const permisoId = 1; // crear_post permission

const success = await revokePermisoFromRole(roleId, permisoId);

if (success) {
  console.log('Permission revoked successfully');
}

Revoking permissions affects all users with that role immediately. Ensure this change aligns with your security policies.

Revoke Multiple Permissions from Role

Function Reference: revokeManyPermisosFromRole(rolId, permisoIds) - rbacService.ts:264

Revokes multiple permissions from a role in a single operation.

Request

DELETE /api/rbac/roles/:rolId/permissions

Parameters

rolId

number

required

The ID of the role to revoke permissions from

permisoIds

number[]

required

Array of permission IDs to revoke from the role

Response

success

boolean

true if all permissions were successfully revoked, false otherwise

Example

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

const rolId = 3; // Editor role
const permisoIds = [3, 20]; // eliminar_post, rechazar_post

const success = await revokeManyPermisosFromRole(rolId, permisoIds);

if (success) {
  console.log('All permissions revoked successfully');
}

Helper Functions

Check Role Permission

Function Reference: roleHasPermiso(rolId, permisoNombre) - rbacService.ts:287

Checks if a specific role has a particular permission by name.

Parameters

rolId

number

required

The role ID to check

permisoNombre

string

required

The permission name to look for (e.g., “crear_post”)

Response

hasPermission

boolean

true if the role has the specified permission, false otherwise

Example

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

const hasPermission = await roleHasPermiso(4, 'publicar_post');

if (hasPermission) {
  console.log('Escritor role can publish posts');
}

Get Role Permissions

Function Reference: getPermisosDeRol(rolId) - rbacService.ts:308

Retrieves all permissions assigned to a specific role.

Parameters

rolId

number

required

The role ID to fetch permissions for

Response

permissions

Permiso[]

Array of permission objects assigned to the role

Example

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

const rolId = 2; // Administrador
const permissions = await getPermisosDeRol(rolId);

console.log('Admin permissions:', permissions);
// [{ id: 1, nombre: 'crear_post', ... }, { id: 2, nombre: 'editar_post', ... }]

Type Definitions

Permiso Interface

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

Permission Type

The types.ts file defines all available permission types:

type Permission = 
  | 'admin_completo'
  | 'asignar_roles'
  | 'comentar'
  | 'crear_categoria'
  | 'crear_post'
  | 'editar_categoria'
  | 'editar_post_cualquiera'
  | 'editar_post_propio'
  | 'eliminar_categoria'
  | 'publicar_post'
  | 'reaccionar'
  | 'rechazar_post';

Best Practices

Permission Granularity

Keep permissions specific and focused on single capabilities
Use separate permissions for different levels of access (e.g., editar_post_propio vs editar_post_cualquiera)
Follow the principle of least privilege when assigning permissions
Document custom permissions thoroughly

Role-Permission Mapping

Regularly audit role-permission assignments
Use getPermisosByRole() to review the complete permission landscape
Test permission changes in a staging environment first
Maintain documentation of which roles should have which permissions

Security Considerations

Never grant admin_completo permission to roles that don’t require it
Monitor permission assignments for compliance with security policies
Implement proper authentication checks before permission operations
Log all permission changes for audit trails

Error Handling

Always verify the role and permission IDs exist before assignment
Check return values from assignment/revocation operations
Implement proper error messages for failed operations
Handle edge cases like duplicate assignments gracefully

Permission Matrix Example

Here’s a typical permission matrix for the predefined roles:

Permission	Creador	Administrador	Editor	Escritor	Autor	Comentador
admin_completo	✅	❌	❌	❌	❌	❌
asignar_roles	✅	✅	❌	❌	❌	❌
crear_post	✅	✅	✅	✅	✅	❌
editar_post_cualquiera	✅	✅	✅	❌	❌	❌
editar_post_propio	✅	✅	✅	✅	✅	❌
publicar_post	✅	✅	✅	❌	✅	❌
crear_categoria	✅	✅	✅	❌	❌	❌
eliminar_categoria	✅	✅	❌	❌	❌	❌
comentar	✅	✅	✅	✅	✅	✅
reaccionar	✅	✅	✅	✅	✅	✅

Roles API

Manage roles and role assignments

User Management

Manage users and their role assignments

Authentication

Posts

Users

Comments

Categories

RBAC

​Overview

​Permission Types

admin_completo

asignar_roles

comentar

crear_categoria

crear_post

editar_categoria

editar_post_cualquiera

editar_post_propio

eliminar_categoria

publicar_post

reaccionar

rechazar_post

​Get All Permissions

​Request

​Response

​Example

​Create Permission

​Request

​Parameters

​Response

​Example

​Delete Permission

​Request

​Parameters

​Response

​Example

​Delete Multiple Permissions

​Request

​Parameters

​Response

​Example

​Get Permissions by Role

​Request

​Response

​Example

​Assign Permission to Role

​Request

​Parameters

​Response

​Example

​Revoke Permission from Role

​Request

​Parameters

​Response

​Example

​Revoke Multiple Permissions from Role

​Request

​Parameters

​Response

​Example

​Helper Functions

​Check Role Permission

​Parameters

​Response

​Example

​Get Role Permissions

​Parameters

​Response

​Example

​Type Definitions

​Permiso Interface

​Permission Type

​Best Practices

​Permission Matrix Example

​Related Resources

Roles API

User Management

Build docs developers (and LLMs) love

Overview

Permission Types

Get All Permissions

Request

Response

Example

Create Permission

Request

Parameters

Response

Example

Delete Permission

Request

Parameters

Response

Example

Delete Multiple Permissions

Request

Parameters

Response

Example

Get Permissions by Role

Request

Response

Example

Assign Permission to Role

Request

Parameters

Response

Example

Revoke Permission from Role

Request

Parameters

Response

Example

Revoke Multiple Permissions from Role

Request

Parameters

Response

Example

Helper Functions

Check Role Permission

Parameters

Response

Example

Get Role Permissions

Parameters

Response

Example

Type Definitions

Permiso Interface

Permission Type

Best Practices

Permission Matrix Example

Related Resources