Permission Management

version tip

This module has been added since v5.0.0.

@cloudbase/manager-node provides PermissionService, accessible via app.permission, and supports two major features:

1. Resource Permission Management: set and query access permissions for SCF, databases, storage, and other resources
2. Role Management: create/query/modify/delete user roles (RBAC), and bind gateway access policies to roles

---

modifyResourcePermission

1. API Description

API feature: Set access permissions for specified resources.

API declaration: app.permission.modifyResourcePermission(options): Promise<Object>

2. Input Parameters

Field	Required	Type	Description
resourceType	Yes	PermissionResourceType	Resource type. Valid values: function / storage / table / collection
resource	No	String	Resource name (e.g., function name, collection name). Can be omitted when resourceType is function
permission	Required	BasePermission	Permission type (See table below)
securityRule	No	String	Custom security rule JSON string. Only required when permission = 'CUSTOM'

Permission Type (BasePermission)

table / collection

Value	Description
READONLY	Read all data, modify own data
PRIVATE	Read and modify own data
ADMINWRITE	Read all data, cannot modify data
ADMINONLY	No permissions
CUSTOM	Custom security rules (Only supported for collection)

storage

Value	Description
READONLY	Readable by all users, writable only by the creator and administrators
PRIVATE	Readable and writable only by the creator and administrators
ADMINWRITE	Readable by all users, writable only by administrators
ADMINONLY	Readable and writable only by administrators
CUSTOM	Custom security rules

function

Value	Description
CUSTOM	Custom security rules

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.Success	Boolean	whether the setting was successful

4. Sample Code

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  // Set the database collection to be readable and writable only by administrators
  await app.permission.modifyResourcePermission({
    resourceType: 'collection',
    resource: 'my-collection',
    permission: 'ADMINONLY'
  })

  // Set custom security rules
  await app.permission.modifyResourcePermission({
    resourceType: 'collection',
    resource: 'user-data',
    permission: 'CUSTOM',
    securityRule: JSON.stringify({
      read: 'auth.uid == doc.uid',
      write: 'auth.uid == doc.uid'
    })
  })
}

test()

---

describeResourcePermission

1. API Description

API feature: Query the current access permissions of specified resources.

API declaration: app.permission.describeResourcePermission(options): Promise<Object>

2. Input Parameters

Field	Required	Type	Description
resourceType	Yes	PermissionResourceType	Resource type: function / storage / table / collection
resources	No	string[]	List of resource names. For SCF, pass an empty array or do not pass this parameter; for cloud storage, pass the bucket name; for database tables, pass the table name. The list cannot exceed 100 entries.

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.TotalCount	Number	Total count
Data.PermissionList	ResourcePermission[]	Permission list

ResourcePermission

Field	Type	Description
ResourceType	String	Resource type
Resource	String	Resource name
Permission	String	Current permission value
SecurityRule	String	Custom security rule (present when permission is CUSTOM)

---

Role management is applicable to scenarios such as multi-person collaboration within enterprises and gateway API access control, supporting the binding of Tencent Cloud gateway policies to roles.

createRole

1. API Description

API feature: Create user role

API declaration: app.permission.createRole(options): Promise<CreateRoleResp>

2. Input Parameters

Field	Required	Type	Description
roleName	Required	String	Role name
roleIdentity	Required	String	Unique identifier for the role (in English, cannot be modified after creation)
description	No	String	Role description
memberUids	No	string[]	Initial member UID list
policies	No	PermissionPolicyItem[]	List of bound permission policies

PermissionPolicyItem

Currently ResourceType only supports gateway.

Field	Required	Type	Description
ResourceType	Required	String	Resource type. Currently only supports gateway
Resource	Required	String	Resource identifier. Fill in the preset policy string when passing a preset policy; must match GatewayPolicyCode when passing a custom policy
Effect	Required	String	Effect: allow (is allowed) or deny (is denied)
GatewayPolicyCode	Required	String	Gateway policy code. Fill in the preset policy string when passing a preset policy; must match Resource when passing a custom policy
GatewayPolicyName	No	String	Gateway policy name
GatewayPolicyDescription	No	String	Gateway policy description
GatewayPolicyExpression	No	String	Gateway policy expression JSON string

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.RoleId	String	Created Role ID
Data.MemberUids	string[]	Added member UID list
Data.Policies	PermissionPolicyItem[]	Bound policy list

4. Sample Code

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  const result = await app.permission.createRole({
    roleName: 'Read-only Operations',
    roleIdentity: 'read-only-operator',
    description: 'Read-only Operations Role',
    policies: [
      { ResourceType: 'gateway', Resource: 'FunctionsAccess', Effect: 'allow', GatewayPolicyCode: 'FunctionsAccess' }
    ]
  })
  console.log('Created Role ID:', result.RoleId)
}

test()

---

describeRoleList

1. API Description

API feature: List roles, supporting filtering by role ID, identifier, and name.

API declaration: app.permission.describeRoleList(options?): Promise<DescribeRoleListResp>

2. Input Parameters

Field	Required	Type	Description
pageNumber	No	Number	Page number, default: 1
pageSize	No	Number	Number of items per page, default: 20
roleId	No	String	Exact match by role ID
roleIdentity	No	String	Query by role unique identifier
roleName	No	String	Query by role name with fuzzy search
loadDetails	No	Boolean	Whether to return member and policy details, default false

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.TotalCount	Number	Total system roles
Data.CustomTotalCount	Number	Total custom roles
Data.SystemRoles	RoleItem[]	System predefined role list
Data.CustomRoles	RoleItem[]	Custom role list

RoleItem

Field	Type	Description
RoleId	String	Role ID
RoleIdentity	String	Unique identifier for the role
RoleName	String	Role name
RoleType	String	Type: system / custom
Description	String	Role description
Members	MemberInfo[]	Member list (returned when loadDetails=true)
Policies	PermissionPolicyItem[]	Policy list (returned when loadDetails=true)

---

modifyRole

1. API Description

API feature: Modify role information, supporting updates to name, description, members, and policies.

API declaration: app.permission.modifyRole(options): Promise<ModifyRoleResp>

2. Input Parameters

Field	Required	Type	Description
roleId	Required	String	Role ID to be modified
roleName	No	String	New role name
description	No	String	New role description
addMemberUids	No	string[]	Added member UID list
removeMemberUids	No	string[]	Member UID list to remove
addPolicies	No	PermissionPolicyItem[]	Added policies list
removePolicies	No	PermissionPolicyItem[]	Policies list to remove

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.Success	Boolean	whether the modification was successful
Data.AddedMemberUids	string[]	Added members
Data.RemovedMemberUids	string[]	Removed members
Data.AddedPolicies	PermissionPolicyItem[]	Added policies
Data.RemovedPolicies	PermissionPolicyItem[]	Removed policies

---

deleteRoles

1. API Description

API feature: Batch delete roles

API declaration: app.permission.deleteRoles(options): Promise<DeleteRolesResp>

2. Input Parameters

Field	Required	Type	Description
roleIds	Required	string[]	List of role IDs to be deleted

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
Data.SuccessCount	Number	Successful deletion count
Data.FailedCount	Number	Failed deletion count

4. Sample Code

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  // Query all custom roles
  const { CustomRoles } = await app.permission.describeRoleList({
    loadDetails: true
  })
  console.log('Custom roles count:', CustomRoles?.length)
  
  // Modify role: Add new member
  await app.permission.modifyRole({
    roleId: 'role-123',
    addMemberUids: ['uid-456'],
    roleName: 'Operations Administrator (Updated)'
  })

  // Delete role
  const res = await app.permission.deleteRoles({
    roleIds: ['role-123', 'role-456']
  })
  console.log(`Successfully deleted ${res.SuccessCount} roles`)
}

test()