Role Management API

Overview

The Role Management API provides endpoints for managing user roles, permissions, and access control in jshERP. Roles define what actions users can perform and what data they can access. Base Path: /role

Roles are essential for implementing role-based access control (RBAC) throughout the system.

CRUD Operations

Get Role Information

GET /role/info?id={id}

Retrieves detailed information for a specific role.

long

required

Role ID

code

integer

Response status code (200 for success)

info

object

Role entity object

Show Role Fields

long

Role ID

name

string

Role name

type

string

Role type (e.g., “public”, “tenant”)

priceLimit

string

Price visibility limitations

value

string

Role value/identifier

description

string

Role description

enabled

boolean

Role enabled status

sort

string

Sort order

tenantId

long

Associated tenant ID

curl -X GET "http://localhost:9999/jshERP-boot/role/info?id=1" \
  -H "Authorization: Bearer {token}"

Get Role List

GET /role/list?search={search}

Retrieves a paginated list of roles with optional filtering.

string

JSON string containing search filters:

name: Filter by role name
description: Filter by description

rows

array

Array of RoleEx objects with extended information

total

integer

Total number of records

curl -X GET "http://localhost:9999/jshERP-boot/role/list?search={\"name\":\"admin\"}" \
  -H "Authorization: Bearer {token}"

Create Role

POST /role/add

Creates a new role.

name

string

required

Role name (must be unique)

type

string

required

Role type:

public: System-wide role
tenant: Tenant-specific role

value

string

Role value/identifier

description

string

Role description

priceLimit

string

Price visibility configuration:

0: No price limit (can see all prices)
1: Purchase price hidden
2: Retail price hidden
3: Sale price hidden

enabled

boolean

default:"true"

Role enabled status

sort

string

Sort order for display

{
  "name": "Sales Manager",
  "type": "tenant",
  "value": "sales_manager",
  "description": "Manages sales operations",
  "priceLimit": "1",
  "enabled": true,
  "sort": "10"
}

Update Role

PUT /role/update

Updates an existing role’s configuration.

long

required

Role ID

name

string

Role name

type

string

Role type

value

string

Role value/identifier

description

string

Role description

priceLimit

string

Price visibility configuration

enabled

boolean

Role enabled status

sort

string

Sort order

Delete Role

DELETE /role/delete?id={id}

Deletes a role (soft delete).

Deleting a role will affect all users assigned to that role. Ensure users are reassigned before deletion.

long

required

Role ID to delete

Batch Delete Roles

DELETE /role/deleteBatch?ids={ids}

Deletes multiple roles in a single operation.

ids

string

required

Comma-separated role IDs (e.g., “1,2,3”)

Role Management

Check Role Name Exists

GET /role/checkIsNameExist?id={id}&name={name}

Checks if a role name is already in use.

long

required

Role ID (0 for new role)

name

string

Role name to check

status

boolean

true if name exists, false otherwise

Find User Roles

GET /role/findUserRole?UBType={type}&UBKeyId={keyId}

Retrieves roles for a specific user with checked status for role assignment.

UBType

string

required

User business type (e.g., “UserRole”)

UBKeyId

string

required

User business key ID (typically user ID)

array

Array of role objects with checked status

Show Role Item Structure

long

Role ID

text

string

Role name

checked

boolean

Whether this role is assigned to the user

curl -X GET "http://localhost:9999/jshERP-boot/role/findUserRole?UBType=UserRole&UBKeyId=123" \
  -H "Authorization: Bearer {token}"

Get All Roles

GET /role/allList

Retrieves a complete list of all roles without pagination.

array

Array of all Role objects

[
  {
    "id": 1,
    "name": "Administrator",
    "type": "public",
    "enabled": true
  },
  {
    "id": 2,
    "name": "Sales Manager",
    "type": "tenant",
    "enabled": true
  }
]

Get Tenant Role List

GET /role/tenantRoleList

Retrieves roles specific to the current tenant.

array

Array of Role objects belonging to the current tenant

Batch Set Role Status

POST /role/batchSetStatus

Enables or disables multiple roles at once.

status

boolean

required

Status to set:

true: Enable roles
false: Disable roles

ids

string

required

Comma-separated role IDs

{
  "status": true,
  "ids": "1,2,3"
}

Data Models

Role Entity

long

Unique role identifier

name

string

Role name (displayed to users)

type

string

Role type:

public: System-wide role available to all tenants
tenant: Tenant-specific role

priceLimit

string

Price visibility restrictions:

0: No restrictions
1: Purchase price hidden
2: Retail price hidden
3: Sale price hidden

value

string

Role value/identifier (used in code)

description

string

Detailed description of the role’s purpose

enabled

boolean

Role enabled status:

true: Role is active and can be assigned
false: Role is disabled

sort

string

Sort order for display purposes

tenantId

long

Associated tenant ID (null for public roles)

deleteFlag

string

Soft delete flag (used internally)

Role Types

Public Roles

System-wide roles defined by administrators
Available across all tenants
Cannot be modified by tenant users
Examples: Administrator, System Manager

Tenant Roles

Created and managed by tenant administrators
Specific to individual tenants
Can be customized per tenant needs
Examples: Sales Manager, Warehouse Staff

Price Limit Configuration

The priceLimit field controls what price information users with this role can view:

Value	Description	Hidden Prices
0	No limit	None (full access)
1	Purchase price hidden	Purchase/cost prices
2	Retail price hidden	Retail prices
3	Sale price hidden	Sale prices

Use price limits to restrict sensitive pricing information from users who don’t need access to it, such as hiding purchase costs from sales staff.

Common Use Cases

Creating a New Role

Check if the role name exists using /role/checkIsNameExist
Create the role using /role/add with appropriate permissions
Configure price limits if needed
Assign the role to users

Assigning Roles to Users

Get the user’s current roles using /role/findUserRole
Update the user’s role assignments through the user business API
Verify the changes by checking user permissions

Managing Role Hierarchy

Use the sort field to establish role display order
Public roles typically have lower sort values
Tenant-specific roles follow the public roles

Best Practices

Role Naming: Use clear, descriptive names that indicate the role’s purpose and permissions level.

Price Limits: Carefully configure price limits based on business requirements. Consider what information each role needs to perform their job effectively.

Role Deletion: Always check for users assigned to a role before deleting it. Consider disabling the role instead of deleting it.

Tenant Isolation: Tenant roles are isolated per tenant. Each tenant can create roles with the same name without conflicts.

Permissions and Access Control

Roles work in conjunction with other permission systems:

Button Permissions: Control which UI buttons are visible
Module Permissions: Control access to different modules
Data Permissions: Control what data can be viewed/modified
Price Limits: Control price information visibility

Error Codes

Code	Description
200	Success
500	Internal server error

All endpoints return a standard response format with code and data fields. Check the code field to determine success or failure.

Overview

Business Operations

System APIs

Role Management API

Overview

CRUD Operations

Get Role Information

Get Role List

Create Role

Update Role

Delete Role

Batch Delete Roles

Role Management

Check Role Name Exists

Find User Roles

Get All Roles

Get Tenant Role List

Batch Set Role Status

Data Models

Role Entity

Role Types

Public Roles

Tenant Roles

Price Limit Configuration

Common Use Cases

Creating a New Role

Assigning Roles to Users

Managing Role Hierarchy

Best Practices

Permissions and Access Control

Error Codes

Build docs developers (and LLMs) love

Overview

Business Operations

System APIs

​Overview

​CRUD Operations

​Get Role Information

​Get Role List

​Create Role

​Update Role

​Delete Role

​Batch Delete Roles

​Role Management

​Check Role Name Exists

​Find User Roles

​Get All Roles

​Get Tenant Role List

​Batch Set Role Status

​Data Models

​Role Entity

​Role Types

​Public Roles

​Tenant Roles

​Price Limit Configuration

​Common Use Cases

​Creating a New Role

​Assigning Roles to Users

​Managing Role Hierarchy

​Best Practices

​Permissions and Access Control

​Error Codes

Build docs developers (and LLMs) love

Overview

CRUD Operations

Get Role Information

Get Role List

Create Role

Update Role

Delete Role

Batch Delete Roles

Role Management

Check Role Name Exists

Find User Roles

Get All Roles

Get Tenant Role List

Batch Set Role Status

Data Models

Role Entity

Role Types

Public Roles

Tenant Roles

Price Limit Configuration

Common Use Cases

Creating a New Role

Assigning Roles to Users

Managing Role Hierarchy

Best Practices

Permissions and Access Control

Error Codes