Role & Permission Endpoints

Manage roles, permissions, and role-permission assignments. Roles define what actions users can perform within a tenant.

Base Paths

Resource	Path
Roles	/api/roles
Role Permissions	/api/role-permissions

Built-in Roles

Role	Description
SUPER_ADMIN	Full system access, tenant management
ADMIN	Organization management, user management
DATA_ENTRY	Data input and basic CRUD operations
EMPLOYEE	Standard employee with limited access
CANDIDATE	Job candidate with minimal access
MANAGER	Team/department management
VIEWER	Read-only access

Role Endpoints

List All Roles

GET /api/roles
Authorization: Bearer {token}

Response 200 OK:

{
  "items": [
    {
      "id": "uuid",
      "name": "ADMIN",
      "isSystem": true,
      "tenantId": "uuid"
    }
  ],
  "total": 7
}

Find Role by Options

GET /api/roles/options?name=EMPLOYEE
Authorization: Bearer {token}

Create Role

POST /api/roles
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "CUSTOM_ROLE"
}

Update Role

PUT /api/roles/:id
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "UPDATED_ROLE_NAME"
}

Delete Role

DELETE /api/roles/:id
Authorization: Bearer {token}

Import Roles (Cloud Migration)

POST /api/roles/import/migrate
Authorization: Bearer {token}
Content-Type: application/json

[
  { "name": "CUSTOM_ROLE_1", "isSystem": false }
]

Role Permission Endpoints

List Permissions for Role

GET /api/role-permissions?roleId={roleId}
Authorization: Bearer {token}

Assign Permission to Role

POST /api/role-permissions
Authorization: Bearer {token}
Content-Type: application/json

{
  "roleId": "uuid",
  "permission": "ORG_USERS_VIEW",
  "enabled": true
}

Update Permission

PUT /api/role-permissions/:id
Authorization: Bearer {token}
Content-Type: application/json

{
  "enabled": false
}

Remove Permission from Role

DELETE /api/role-permissions/:id
Authorization: Bearer {token}

Available Permissions

Category	Permissions
Organization	ORG_USERS_VIEW, ORG_USERS_EDIT, ALL_ORG_VIEW, ALL_ORG_EDIT
Employees	ORG_EMPLOYEES_VIEW, ORG_EMPLOYEES_EDIT
Time	TIME_TRACKER, ALLOW_MANUAL_TIME, ALLOW_DELETE_TIME
Tasks	ORG_TASK_VIEW, ORG_TASK_EDIT, ORG_TASK_ADD
Projects	ORG_PROJECT_VIEW, ORG_PROJECT_EDIT, ORG_PROJECT_ADD
Sprints	ORG_SPRINT_VIEW, ORG_SPRINT_ADD, ORG_SPRINT_EDIT, ORG_SPRINT_DELETE
Invoices	ORG_EXPENSES_VIEW, ORG_EXPENSES_EDIT, INVOICES_VIEW, INVOICES_EDIT
CRM	VIEW_SALES_PIPELINES, EDIT_SALES_PIPELINES
Roles	CHANGE_ROLES_PERMISSIONS
Integration	INTEGRATION_VIEW, INTEGRATION_EDIT
System	MIGRATE_GAUZY_CLOUD, ACCESS_DELETE_ACCOUNT, ACCESS_DELETE_ALL_DATA

Data Model

interface IRole {
  id: string;
  name: string;
  isSystem: boolean;
  tenantId: string;
  rolePermissions?: IRolePermission[];
}

interface IRolePermission {
  id: string;
  roleId: string;
  permission: string;
  enabled: boolean;
  tenantId: string;
}

Permissions

Action	Required Permission
View/manage roles	CHANGE_ROLES_PERMISSIONS
View roles (team)	ORG_TEAM_ADD

Related Pages

• Roles and Permissions — conceptual guide
• User Endpoints — user management
• Authentication Flows — auth security