Auth API

About 1661 wordsAbout 6 min

2026-01-09

This document consolidates the original AuthAPI.md and AuthUserAPI.md. Use this file as the source of truth.

Entry Functions

Fx.auth.getUser

Query with user as the subject.

Fx.auth.getUser()

Reference interface:

com.fxiaoke.functions.api.AuthUserAPI

Fx.auth.getRole

Query with role as the subject.

Fx.auth.getRole()

Reference interface:

com.fxiaoke.functions.api.AuthRoleAPI

Fx.auth.getOuterUser

Query with external user as the subject.

Fx.auth.getOuterUser()

Reference interface:

com.fxiaoke.functions.api.AuthOuterUserAPI

AuthUserAPI

getRolesByUsers

Query all roles for users, with user as the subject.

AuthUserAPI.getRolesByUsers(<string roleSource>, <array userIds>)

Parameters

Input format

Parameter	Type	Description	Required
roleSource	string	Role type. `1` for internal role, `2` for external role	Yes
userIds	array[string]	Employee IDs	Yes

Output format

Parameter	Type	Description
appId	string
userId	string
roleCode	string
majorRole	boolean
outerTenantId	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

def(boolean error, List data, String message) = Fx.auth.user.getRolesByUsers(1, ["1001"])
if (error) {
  log.info("error: " + message)
} else {
  log.info(data)
}

getUsersByRoleCodes

Query all users for roles, with role as the subject.

AuthUserAPI.getUsersByRoleCodes(<array roleCodes>)

Parameters

Input format

Parameter	Type	Description	Required
roleCodes	array[string]	Role code list	Yes

Output format

Parameter	Type	Description
appId	string
userId	string
roleCode	string
majorRole	boolean
outerTenantId	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

List roleCodes = ["00000000000000000000000000000009"]
def(boolean error, List data, String message) = Fx.auth.user.getUsersByRoleCodes(roleCodes)
if (error) {
  log.info("error: " + message)
} else {
  log.info(data)
}

Owner: Seth

batchAddUserRole

Append roles.

AuthUserAPI.batchAddUserRole(<array roleCodes>, <boolean updateMajorRole>, <string majorRole>, <array userIds>)

Parameters

Input format

Parameter	Type	Description	Required
roleCodes	array[string]	Role code list	Yes
updateMajorRole	boolean	Whether to update the primary role	Yes
majorRole	string	Primary role code	Yes
userIds	array[string]	User ID list	Yes

Groovy example

def(boolean error, Map data, String message) = Fx.auth.user.batchAddUserRole(
  ["00000000000000000000000000000009"],
  true,
  "00000000000000000000000000000009",
  ["1069"]
)
if (error) {
  log.info("error: " + message)
} else {
  log.info(data)
}

Owner: Seth

batchSetUserRoles

Set user roles. Submitted parameters take precedence.

AuthUserAPI.batchSetUserRoles(<array userIds>, <array roleCodes>, <string majorRole>)

Parameters

Input format

Parameter	Type	Description	Required
userIds	array[string]	User ID list	Yes
roleCodes	array[string]	Role code list	Yes
majorRole	string	Primary role code	Yes

Groovy example

def(boolean error, Map data, String message) = Fx.auth.user.batchSetUserRoles(
  ["1046"],
  ["00000000000000000000000000000009", "00000000000000000000000000000014"],
  "00000000000000000000000000000014"
)
if (error) {
  log.info("error: " + message)
} else {
  log.info(data)
}

Owner: Seth

deleteByUserIds

Delete users with role as the subject.

AuthUserAPI.deleteByUserIds(<string roleCode>, <array userIds>)

Parameters

Input format

Parameter	Type	Description	Required
roleCode	string	Role code	Yes
userIds	array[string]	User ID list	Yes

Output format

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

def(boolean error, Map data, String message) = Fx.auth.user.deleteByUserIds(
  "00000000000000000000000000000009",
  ["1267"]
)
if (error) {
  log.info("error: " + message)
} else {
  log.info(data)
}

Owner: Seth

queryUsedCRM

Query how many CRM roles are used by the tenant.

AuthUserAPI.queryUsedCRM()

Parameters

Output format

Parameter	Type	Description
usedQuotaSize	integer	Used quota count

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

def(boolean error, Map data, String message) = Fx.auth.user.queryUsedCRM()
if (error) {
  log.info("error: " + message)
} else {
  log.info(data)
}

Owner: Seth

getUsersByRoleCodesWithAppId

Query all users for roles, with role as the subject.

AuthUserAPI.getUsersByRoleCodesWithAppId(<string appId>, <array roleCodes>)

Parameters

Input format

Parameter	Type	Description	Required
appId	string	App ID	Yes
roleCodes	array[string]	Role code list	Yes

Output format

Parameter	Type	Description
appId	string
userId	string
roleCode	string
majorRole	boolean
outerTenantId	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

List roleCodes = ["00000000000000000000000000000009"]
String appId = "facishare-system"
def(boolean error, List data, String message) = Fx.biz.callAPI("getUsersByRoleCodesWithAppId", appId, roleCodes)
if (error) {
  log.info("error: " + message)
} else {
  log.info(data)
}

AuthRoleAPI

getRoleList

Query role list.

AuthRoleAPI.getRoleList(<array appIds>, <string roleSource>)

Parameters

Input format

Parameter	Type	Description	Required
appIds	array[string]	App ID list	Yes
roleSource	string	Role source	Yes

Output format

Parameter	Type	Description
list	array[object]	Role list

list	Type	Description
groupName	string
roleName	string
roleCode	string
roleType	integer
appId	string
tenantId	string
description	string
delFlag	boolean
roleOrder	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

List appIds = ["facishare-system"]
String roleSource = "1"
def(boolean error, List data, String message) = Fx.auth.role.getRoleList(appIds, roleSource)
if (error) {
  log.info("error: " + message)
} else {
  log.info(data)
}

Owner: Seth

createAdminRole

Create an admin-function permission role.

AuthRoleAPI.createAdminRole(<string roleName>, <string description>, <string roleType>, <string sourceRoleCode>, <string appId>, <string licenseCode>)

Parameters

Input format

Parameter	Type	Description	Required
roleName	string	Role name	Yes
description	string	Role description	Yes
roleType	string	Role type	Yes
sourceRoleCode	string	Source role code	Yes
appId	string	App ID	Yes
licenseCode	string	License code	Yes

Output format

Parameter	Type	Description
roleCode	string
errorReason	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

String roleName = "Custom admin permission"
String description = "Custom admin permission description"
String roleType = "admin"
String sourceRoleCode = "source-role-code"
String appId = "facishare-system"
String licenseCode = "license-code"
def (boolean error, Map returnObj, String message) = Fx.auth.role.createAdminRole(
  roleName,
  description,
  roleType,
  sourceRoleCode,
  appId,
  licenseCode
)
if (error) {
  log.info("=====" + message)
} else {
  log.info("returnObj:" + returnObj)
}

Owner: Seth

createRole

Create a role.

AuthRoleAPI.createRole(<string appId>, <string roleName>, <array functionCodes>, <string description>)

Parameters

Input format

Parameter	Type	Description	Required
appId	string	App ID	Yes
roleName	string	Role name	Yes
functionCodes	array[string]	Function code list	Yes
description	string	Role description	Yes

Output format

Parameter	Type	Description
roleCode	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

String appId = "facishare-system"
String roleName = "Custom admin permission"
List functionCodes = ["function-code-1"]
String description = "Custom admin permission description"
def (boolean error, Map returnObj, String message) = Fx.auth.role.createRole(
  appId,
  roleName,
  functionCodes,
  description
)
if (error) {
  log.info("=====" + message)
} else {
  log.info("returnObj:" + returnObj)
}

Owner: Seth

deleteRole

Delete a role.

AuthRoleAPI.deleteRole(<string roleCode>, <boolean isManagement>)

Parameters

Input format

Parameter	Type	Description	Required
roleCode	string	Role code	Yes
isManagement	boolean	Whether it is a management role	Yes

Output format

Parameter	Type	Description
roleCode	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

String roleCode = "1234"
boolean isManagement = false
def (boolean error, Map returnObj, String message) = Fx.auth.role.deleteRole(roleCode, isManagement)
if (error) {
  log.info("=====" + message)
} else {
  log.info("returnObj:" + returnObj)
}

Owner: Seth

updateRole

Update a role.

AuthRoleAPI.updateRole(<string roleCode>, <string roleName>, <string description>, <string roleGroupCode>)

Parameters

Input format

Parameter	Type	Description	Required
roleCode	string	Role code	Yes
roleName	string	Role name	Yes
description	string	Role description	Yes
roleGroupCode	string	Role group code	Yes

Output format

Parameter	Type	Description
roleCode	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

String roleCode = "1234"
String roleName = "Custom admin permission"
String description = "Custom admin permission description"
String roleGroupCode = "roleGroupCode1"
def (boolean error, Map returnObj, String message) = Fx.auth.role.updateRole(
  roleCode,
  roleName,
  description,
  roleGroupCode
)
if (error) {
  log.info("=====" + message)
} else {
  log.info("returnObj:" + returnObj)
}

Owner: Seth

replicateRole

Copy a role. CRM admin roles cannot be copied.

AuthRoleAPI.replicateRole(<string fromRoleCode>, <string roleName>, <string description>, <string roleGroupCode>, <boolean isManagement>)

Parameters

Input format

Parameter	Type	Description	Required
fromRoleCode	string	Source role code	Yes
roleName	string	Role name	Yes
description	string	Role description	Yes
roleGroupCode	string	Role group code	Yes
isManagement	boolean	Whether it is a management role	Yes

Groovy example

String fromRoleCode = "1234"
String roleName = "Custom admin permission"
String description = "Custom admin permission description"
String roleGroupCode = "roleGroupCode1"
boolean isManagement = false
def (boolean error, Map returnObj, String message) = Fx.auth.role.replicateRole(
  fromRoleCode,
  roleName,
  description,
  roleGroupCode,
  isManagement
)
if (error) {
  log.info("=====" + message)
} else {
  log.info("returnObj:" + returnObj)
}

Owner: Seth

deleteAdminRole

Delete an admin-function permission role.

AuthRoleAPI.deleteAdminRole(<string appId>, <string roleCode>)

Parameters

Input format

Parameter	Type	Description	Required
appId	string	App ID	Yes
roleCode	string	Role code	Yes

Output format

Parameter	Type	Description
error	string
roleCode	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

String appId = "facishare-system"
String roleCode = "1234"
def (boolean error, Map returnObj, String message) = Fx.auth.role.deleteAdminRole(appId, roleCode)
if (error) {
  log.info("=====" + message)
} else {
  log.info("returnObj:" + returnObj)
}

Owner: Seth

updateAdminRole

Update an admin-function permission role.

AuthRoleAPI.updateAdminRole(<string appId>, <string roleCode>, <string roleName>, <string description>)

Parameters

Input format

Parameter	Type	Description	Required
appId	string	App ID	Yes
roleCode	string	Role code	Yes
roleName	string	Role name	Yes
description	string	Role description	Yes

Output format

Parameter	Type	Description
roleCode	string
error	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

String appId = "facishare-system"
String roleCode = "1234"
String roleName = "Custom admin permission"
String description = "Custom admin permission description"
def (boolean error, Map returnObj, String message) = Fx.auth.role.updateAdminRole(
  appId,
  roleCode,
  roleName,
  description
)
if (error) {
  log.info("=====" + message)
} else {
  log.info("returnObj:" + returnObj)
}

Owner: Seth

replicateAdminRole

Copy a role. CRM admin roles cannot be copied.

AuthRoleAPI.replicateAdminRole(<string roleName>, <string description>, <integer roleType>, <string sourceRoleCode>, <string appId>, <string licenseCode>)

Parameters

Input format

Parameter	Type	Description	Required
roleName	string	Role name	Yes
description	string	Role description	Yes
roleType	integer	Role type	Yes
sourceRoleCode	string	Source role code	Yes
appId	string	App ID	Yes
licenseCode	string	License code	Yes

Output format

Parameter	Type	Description
roleCode	string
errorReason	string

Output example

{
  "isError": false,
  "data": {},
  "message": "success"
}

Groovy example

String roleName = "Custom admin permission"
String description = "Custom admin permission description"
Integer roleType = 1
String sourceRoleCode = "sourceRoleCode1"
String appId = "facishare-system"
String licenseCode = "license-code"
def (boolean error, Map returnObj, String message) = Fx.auth.role.replicateAdminRole(
  roleName,
  description,
  roleType,
  sourceRoleCode,
  appId,
  licenseCode
)
if (error) {
  log.info("=====" + message)
} else {
  log.info("returnObj:" + returnObj)
}

Owner: Seth

addRoleWithDepartmentToEmployeesByAppId

Assign management roles to users. CRM admin role can also be assigned.

AuthRoleAPI.addRoleWithDepartmentToEmployeesByAppId()

Groovy example

List employeeIds = [1000]
def currentEmployeeId = 1000
def roleCodeAndDepartmentIds = [
  "roleCode": "31",
  "departmentIds": [999999]
]
def(boolean error, List data, String message) = Fx.auth.role.addRoleWithDepartmentToEmployeesByAppId(
  currentEmployeeId,
  employeeIds,
  roleCodeAndDepartmentIds
)

Owner: Seth

AuthOuterUserAPI

deleteByUserIds

Delete interconnected users with role as the subject.

AuthOuterUserAPI.deleteByUserIds(<array userIds>, <string roleCode>)

Parameters

Input format

Parameter	Type	Description	Required
userIds	array[string]	User ID list	Yes
roleCode	string	Role code	Yes

Groovy example

def (boolean error, Map returnObj, String message) = Fx.auth.outerUser.deleteByUserIds(
  ["1000"],
  "00000000000000000000000000000009"
)
if (error) {
  log.info("error: " + message)
} else {
  log.info("returnObj:" + returnObj)
}

Owner: Seth

updateRoles

Overwrite all roles of interconnected users.

AuthOuterUserAPI.updateRoles(<array userIds>, <string majorRole>, <array roleCodes>)

Parameters

Input format

Parameter	Type	Description	Required
userIds	array[string]	User ID list	Yes
majorRole	string	Primary role code	Yes
roleCodes	array[string]	Role code list	Yes

Groovy example

def (boolean error, Map returnObj, String message) = Fx.auth.outerUser.updateRoles(
  ["300383629"],
  "5b6817bbe4b066655a6397e4",
  ["5b6817bbe4b066655a6397e4"]
)
if (error) {
  log.info("error: " + message)
} else {
  log.info("returnObj:" + returnObj)
}