Roles, Permissions, and Routes

This documentation serves as a technical reference (including for AI) regarding the access levels in the Flowi Agentic platform.

The platform has a Multi-tenant SaaS architecture. Access control is primarily based on the presence (or absence) of the SUPER_ADMIN flag in Keycloak/Store and the user's role within the context of a Tenant.

---

1. Profiles and Access Levels

A. Super Admin (Global Admin)

• Frontend Identification: roles.includes('SUPER_ADMIN')
• Backend Identification: Verification of the global role (via Keycloak token) or absence of the X-Tenant-ID header on restricted /admin/* endpoints.
• Scope: The entire system. Not tied to a specific tenant in the global administration interface.
• Responsibilities: Register tenants, manage global process definitions (BPMN/CMMN), DMN templates, configure AI, and manage all users.

B. Tenant Admin (Tenant Administrator)

• Frontend Identification: !isSuperAdmin && currentTenant?.role === 'ADMIN'
• Backend Identification: Access to resources via /a/* with permission to manipulate tenant metadata, plus CRUD operations for users of that tenant (/admin/tenants/{tenantId}/* which internally validates roles).
• Scope: Restricted to their own Tenant's data.
• Responsibilities: Configure the default Business Key for the tenant, enable/disable published processes in their catalog, manage members of their own tenant (invitations/removals), manage robots (AI Agents), API Keys, and Webhooks for the tenant.

C. Tenant User (Standard User)

• Frontend Identification: currentTenant?.role === 'USER'
• Backend Identification: Restricted access via operational endpoints (/a/*) requiring the X-Tenant-ID header.
• Scope: Restricted to the operation of their own Tenant.
• Responsibilities: Start process instances, execute tasks (/tasks), fill out forms, and view operational dashboards.

---

2. Frontend Routes (React / TanStack Router)

The table below crosses frontend routes with the visibility for each profile:

Route / Path	Module / Function	Super Admin	Tenant Admin	Tenant User
/dashboard	Overview, charts, and counters.	❌ (Uses admin panel)	✅	✅
/admin/tenants	Global listing and creation of tenants.	✅	❌	❌
/admin/users	Global listing of users.	✅	❌	❌
/admin/ai-config	AI provider configuration.	✅	❌	❌
/admin/rag-config	Retrieval-Augmented Generation configuration.	✅	❌	❌
/definitions	Local Definitions (Process Catalog) - For TA: Views published processes, enables/disables, and configures local instances and document types.	❌	✅	❌
/admin/global-templates	Global Templates - For SA: Lists all, allows creating BPMN/CMMN/DMN and configuring global Document Types, Variables, and Attachments.	✅	❌	❌
/admin/process-roles	Centralized catalog for Process Roles.	✅	❌	❌
/admin/global-templates/$key	Template details and advanced configuration tabs.	✅	❌	❌
/instances	Listing of active instances, history, and errors.	❌ (Global management via API only)	✅	✅
/instances/start/*	Form to start instances.	❌ (Restricted to prevent tenant-less instances)	✅	✅
/tasks	Inbox and human task execution.	❌	✅	✅
/cms	Dynamic content management for the tenant.	❌	✅	✅
/decisions	Decision Tables and executed DMN instances.	❌	✅	✅
/robots	Automation and bots linked to the tenant.	❌	✅	❌
/admin/api-keys	Programmatic API keys per tenant.	❌	✅	❌
/admin/webhooks	Configured callbacks per tenant.	❌	✅	❌
/admin/tenants/$id	Tenant member management.	✅	✅	❌

---

3. Backend Endpoints and Permissions (REST API)

The APIs in Spring Boot are divided by URL convention and security filters.

Main Prefixes

1. /admin/**: Global management endpoints.
   • Require SUPER_ADMIN role or equivalent scope.
   • Do not mandatorily require X-Tenant-ID, operating cross-tenant where applicable.
2. /a/**: Multi-tenant operational endpoints.
   • Mandatorily require the X-Tenant-ID header.
   • The backend validates if the authenticated user has the listed tenant in their permissions.

Key Process Control Endpoints

Endpoint	Method	Context	Access	Description
/admin/definitions	GET, POST	Global	SA	General query, deploy XML files to the platform.
/a/definitions	GET	Tenant	TA, User	Returns the active process catalog for the tenant.
/a/definitions/{key}/config	PUT	Tenant	TA	Specific process configuration in the tenant (e.g., Business Key Template).
/a/definitions/{key}/toggle	PATCH	Tenant	TA	Enables/Disables the process in the tenant.
/a/instances	POST	Tenant	TA, User	Starts a workflow instance on behalf of the logged-in tenant. Generates the Business Key according to fallback hierarchy.
/a/instances/search	GET	Tenant	TA, User	Searches for instances based on variables tied to the logged-in tenant.

---

4. Hierarchy Resolution for Business Keys (Note for AI)

The backend resolves initialization variables like the Business Key in a hierarchical order (Implemented in WorkflowDefinitionService):

1. Tenant Configuration (TenantProcessCatalog): The Tenant Admin overrides the global configuration using /a/definitions/{key}/config.
2. Global Configuration (WorkflowDefinition): The Super Admin configures the default for the process via /definitions/$key (or /admin/global-templates).
3. System Default: Hardcoded fallback to DOC-${date:yyyyMMdd}-${random:4}.

This architecture prevents the SA and Tenant from sending hardcoded Business Keys, generating architectural consistency in the Java layer (Flowable).