Configuring Roles

Roles in CONFOR define what users can see and do within the system. This guide explains how to create roles, assign permissions, and manage role-based access control (RBAC).

Overview

CONFOR’s permission system is built on:

Roles: Named collections of permissions (e.g., “Field Manager”, “Accountant”)
Permissions: Granular access rights organized by module and action
Modules: System components like Users, Forest Patrimony, Audit, etc.
Actions: Operations like CREATE, READ, UPDATE, DELETE, EXPORT, ADMIN

Permission Model

Each permission is defined as {module}:{action}, for example:

users:READ - Can view user list
users:CREATE - Can create new users
forest-patrimony:UPDATE - Can edit forestry data
users:ADMIN - Full administrative access to user management

Viewing Roles

Access the Roles page to see all roles in your organization:

Navigate to Roles

From the dashboard, go to Roles y permisos in the main navigation.

You need users:READ or users:ADMIN permission to view roles.

Select Organization

If you manage multiple organizations, select the active organization from the dropdown.The roles table displays:

Rol: Role display name
Slug: Internal identifier (uppercase, underscores)
Organización: Organization name (or “Global” for system roles)
Sistema: Whether this is a protected system role
Permisos: Number of permissions assigned

System Roles vs Custom Roles

System Roles: Pre-defined roles like SUPER_ADMIN, ADMIN, USER
- Cannot be deleted
- Have the “Sistema: Sí” flag
- Provide baseline access patterns
Custom Roles: Organization-specific roles you create
- Can be edited and deleted
- “Sistema: No” flag
- Tailored to your workflow

Creating a New Role

Open Role Creation Form

On the Roles page, click Nuevo rol in the “CRUD de roles” section.

You need users:CREATE or users:ADMIN permission to create roles.

Enter Role Details

Fill in the role metadata:

Nombre: Display name (e.g., “Field Manager”, “Data Analyst”)
Slug: Internal identifier (e.g., “FIELD_MANAGER”)
- Will be auto-normalized to UPPERCASE with underscores
- Must be unique within your organization
Descripción: Optional description of the role’s purpose

Example:
Nombre:      Field Manager
Slug:        FIELD_MANAGER
Descripción: Manages field data collection and forest inventory

Click Create

Click Crear rol to save the new role.The role appears in the roles table with 0 permissions. You’ll assign permissions in the next step.

Assigning Permissions to a Role

Open Permissions Modal

In the roles table, find your role and click the Permisos button.A modal opens showing all available modules and their permissions.

Review Available Modules

Common modules include:

users: User and role management
forest-patrimony: Forest hierarchy (Levels 2-5)
audit: Audit log viewing
organizations: Organization management
system-config: System configuration

Each module displays its available actions:

CREATE
READ
UPDATE
DELETE
EXPORT (if applicable)
ADMIN (full module access)

Assign CRUD Permissions

For quick setup, use the CRUD completo checkbox for each module:

“CRUD completo” grants CREATE, READ, UPDATE, and DELETE permissions together.

This is ideal for roles that need full operational access to a module.

Fine-Tune Individual Permissions

For granular control, check/uncheck individual action checkboxes:

Example: Read-Only Auditor

Module: users
  ☐ CREATE
  ☑ READ
  ☐ UPDATE
  ☐ DELETE
  ☐ EXPORT
  ☐ ADMIN

Module: audit
  ☐ CREATE
  ☑ READ
  ☐ UPDATE
  ☐ DELETE
  ☐ ADMIN

Use Bulk Actions

The modal provides convenience buttons:

Marcar todo: Select all permissions across all modules
Desmarcar todo: Clear all permissions

Using “Desmarcar todo” will remove ALL permissions, potentially locking users out of the system.

Save Permissions

Click Guardar permisos to apply the changes.The role’s permission count updates in the table.

Permission changes take effect immediately for all users assigned to this role.

Editing a Role

To modify an existing role’s metadata (name, slug, description):

Click Edit Button

In the roles table, click the Editar button for the role you want to modify.The role details populate in the “CRUD de roles” form at the top of the page.

Modify Role Details

Update the:

Nombre: Display name
Slug: Internal identifier (must remain unique)
Descripción: Purpose description

Changing the slug may break integrations that reference the role by its old slug.

Save Changes

Click Actualizar rol to save the modifications.

Deleting Roles

Select Role to Delete

Locate the role in the roles table.

System roles (with “Sistema: Sí”) cannot be deleted and will have a disabled Delete button.

Click Delete

Click the Eliminar button for the role.A confirmation dialog appears.

Confirm Deletion

In the confirmation toast, click Eliminar again.

Deleting a role:

Removes it from all assigned users
Cannot be undone
May lock users out if it was their only role

Bulk Role Deletion

To delete multiple roles at once:

Select Roles

Check the checkboxes next to the roles you want to delete.

System roles cannot be selected for bulk deletion.

Click Bulk Delete

At the bottom of the page, click Eliminar seleccionados (N), where N is the count of selected roles.

Confirm Bulk Deletion

Confirm in the dialog that appears.CONFOR deletes all selected roles in parallel and reports:

Number successfully deleted
Number that failed (if any)

Importing Roles

For bulk role provisioning:

Prepare Import File

Create a CSV or Excel file with columns:

name: Role display name
slug: Role identifier (will be normalized)
description: Optional description
permissions: Comma-separated permission IDs (optional)

name,slug,description
Data Analyst,data_analyst,Analyzes forest inventory data
Field Coordinator,field_coordinator,Coordinates field operations

Click Import

On the Roles page, click Importar.

Upload File

Select your CSV or Excel file.CONFOR processes the import and displays:

Creados: New roles created
Actualizados: Existing roles updated
Omitidos: Duplicate slugs skipped
Errores: Validation errors

Exporting Roles

Export roles for backup or documentation:

Configure Export

Set:

Límite de exportación: Number of roles to export (default: 100)
Use search to filter which roles to export

Choose Format

Click:

Exportar CSV: For spreadsheet software
Exportar Excel: For Microsoft Excel

Download File

The file downloads with a name like roles.csv or roles.xlsx.

Common Role Configurations

Administrator Role

Permissions: All modules with ADMIN action

Role: Administrator
Slug: ADMIN

Permissions:
  users:ADMIN
  forest-patrimony:ADMIN
  audit:ADMIN
  organizations:ADMIN
  system-config:ADMIN

Read-Only Viewer

Permissions: READ only across modules

Role: Viewer
Slug: VIEWER

Permissions:
  users:READ
  forest-patrimony:READ
  audit:READ

Field Data Manager

Permissions: Full CRUD on forest data, read-only elsewhere

Role: Field Manager
Slug: FIELD_MANAGER

Permissions:
  forest-patrimony:CREATE
  forest-patrimony:READ
  forest-patrimony:UPDATE
  forest-patrimony:DELETE
  forest-patrimony:EXPORT
  users:READ
  audit:READ

Auditor

Permissions: Full audit access, read-only elsewhere

Role: Auditor
Slug: AUDITOR

Permissions:
  audit:READ
  audit:EXPORT
  users:READ
  forest-patrimony:READ

Permissions Required

To perform role configuration actions:

Action	Required Permission
View roles list	`users:READ` or `users:ADMIN`
Create roles	`users:CREATE` or `users:ADMIN`
Edit role metadata	`users:UPDATE` or `users:ADMIN`
Assign permissions	`users:UPDATE` or `users:ADMIN`
Delete roles	`users:DELETE` or `users:ADMIN`
Import roles	`users:CREATE` or `users:ADMIN`
Export roles	`users:EXPORT` or `users:ADMIN`

Best Practices

Follow Principle of Least Privilege

Grant users only the permissions they need:

Start with minimal permissions
Add permissions as needed
Regularly review and audit role assignments
Avoid over-using ADMIN permissions

Use Descriptive Role Names

Make role purpose clear from the name:

✅ “Field Manager”, “Data Analyst”, “Reporting Specialist”
❌ “Role1”, “Test”, “New Role”

Include department or function in the name for large organizations.

Document Role Definitions

Maintain documentation about:

What each role is intended for
Which departments use which roles
Permission rationale for each role
When to use each role vs others

Test Roles Before Deployment

Before assigning a new role to production users:

Create a test user account
Assign the new role
Verify all intended workflows function correctly
Check that restricted areas are properly blocked

Avoid Modifying System Roles

System roles (SUPER_ADMIN, ADMIN, USER) provide baseline functionality:

Don’t modify their permissions
Create custom roles for specific needs instead
Use system roles as templates for new roles

Troubleshooting

User Can’t Access a Feature

Check role permissions: Verify the user’s role has the required permission. Multiple roles: If a user has multiple roles, permissions are cumulative. Check all assigned roles. Recent changes: Permission changes take effect immediately, but the user may need to refresh their browser.

Role Creation Fails

Duplicate slug: The slug must be unique within your organization. Try a different identifier. Invalid characters: Slugs are normalized to UPPERCASE with underscores. Avoid special characters. Missing permissions: You need users:CREATE or users:ADMIN to create roles.

Can’t Delete a Role

System role: System roles (with “Sistema: Sí”) cannot be deleted. In use: Consider removing the role from all users before deletion, though this is not strictly required. Permissions: You need users:DELETE or users:ADMIN to delete roles.

API Endpoints

For programmatic role management:

GET    /api/roles              # List roles with permissions
POST   /api/roles              # Create a new role
PATCH  /api/roles              # Update role permissions
PATCH  /api/roles/{id}         # Update role metadata
DELETE /api/roles/{id}         # Delete a role
POST   /api/roles/import       # Bulk import roles
GET    /api/roles/export       # Export roles

Example: Create a Role

curl -X POST "https://your-confor-instance.com/api/roles" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Field Manager",
    "slug": "FIELD_MANAGER",
    "description": "Manages field operations and data collection"
  }'

Example: Assign Permissions

curl -X PATCH "https://your-confor-instance.com/api/roles" \
  -H "Content-Type: application/json" \
  -d '{
    "roleId": "role-uuid-here",
    "permissionIds": [
      "permission-uuid-1",
      "permission-uuid-2",
      "permission-uuid-3"
    ]
  }'

Managing Users - Assign roles to users
Audit Logs - Track role and permission changes
Forest Hierarchy - Understand data access patterns

Get Started

Core Features

User Guides

Configuration

Configuring Roles

Configuring Roles

Overview

Permission Model

Viewing Roles

System Roles vs Custom Roles

Creating a New Role

Assigning Permissions to a Role

Editing a Role

Deleting Roles

Bulk Role Deletion

Importing Roles

Exporting Roles

Common Role Configurations

Administrator Role

Read-Only Viewer

Field Data Manager

Auditor

Permissions Required

Best Practices

Troubleshooting

User Can’t Access a Feature

Role Creation Fails

Can’t Delete a Role

API Endpoints

Example: Create a Role

Example: Assign Permissions

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Configuration

​Configuring Roles

​Overview

​Permission Model

​Viewing Roles

​System Roles vs Custom Roles

​Creating a New Role

​Assigning Permissions to a Role

​Editing a Role

​Deleting Roles

​Bulk Role Deletion

​Importing Roles

​Exporting Roles

​Common Role Configurations

​Administrator Role

​Read-Only Viewer

​Field Data Manager

​Auditor

​Permissions Required

​Best Practices

​Troubleshooting

​User Can’t Access a Feature

​Role Creation Fails

​Can’t Delete a Role

​API Endpoints

​Example: Create a Role

​Example: Assign Permissions

​Related Guides

Build docs developers (and LLMs) love

Configuring Roles

Overview

Permission Model

Viewing Roles

System Roles vs Custom Roles

Creating a New Role

Assigning Permissions to a Role

Editing a Role

Deleting Roles

Bulk Role Deletion

Importing Roles

Exporting Roles

Common Role Configurations

Administrator Role

Read-Only Viewer

Field Data Manager

Auditor

Permissions Required

Best Practices

Troubleshooting

User Can’t Access a Feature

Role Creation Fails

Can’t Delete a Role

API Endpoints

Example: Create a Role

Example: Assign Permissions

Related Guides