Knowledge Base member management

​

Use cases

• Scenario 1: When a new employee onboards, an external collaborator joins, or a department/group needs to access the Knowledge Base, the admin can use this flow to batch-add members and assign roles.
• Scenario 2: When a member is promoted to admin, or you need to restrict a member’s operations, use this flow to change their role.
• Scenario 3: When a member leaves, a project ends, or you need to revoke access for a specific user or department, use this flow to remove them from the Knowledge Base.
• Scenario 4: When the organization wants to make a Knowledge Base (such as company policies or product manuals) accessible to all employees without adding members one by one.
• Scenario 5: Used when you need to audit Knowledge Base permissions, troubleshoot permission issues, or confirm members’ current roles before bulk operations.

​

Permission overview

​

Permission roles (roleId)

Note: The OWNER role cannot be added or removed via the API. The Knowledge Base creator is the owner by default.

​

Member types (members.type)

​

Scenario 1: Grant Knowledge Base access to new members

1. Call the Get Knowledge Base list API and read the rootNodeId field from the response. This is the dentryUuid of the Knowledge Base root node.
2. Get the member ID:
   • To add a user: Call the Query user details API to get the userId, or use Get the list of department userIds to retrieve them in bulk.
   • To add a department: Call the Get department list API to get the deptId.
   • To add a group chat: Use the group’s chatId.
3. Call the Add permissions API and choose the appropriate role based on your business needs (for example, EDITOR for collaborative editing, READER for read-only access) to add members to the Knowledge Base.

   Tips: A single request supports up to 30 members. Split into multiple calls if you exceed this limit.

   POST /v2.0/storage/spaces/dentries/{dentryUuid}/permissions?unionId={operator unionId} HTTP/1.1
   Host: api.dingtalk.io
   x-acs-dingtalk-access-token: {ACCESS_TOKEN}
   Content-Type: application/json
   
   {
     "roleId": "EDITOR",
     "members": [
       { "type": "USER", "id": "employee userId" },
       { "type": "DEPT", "id": "department deptId", "corpId": "organization corpId" }
     ]
   }
   

​

Scenario 2: Adjust a member’s role in the Knowledge Base

1. To confirm a member’s current role, first call the Get permission list API.
2. Call the Modify permissions API and specify the member and target role to change the role.

   Note: A member can hold only one role in the same Knowledge Base. After the change, the old role is automatically replaced.

   PUT /v2.0/storage/spaces/dentries/{dentryUuid}/permissions?unionId={operator unionId} HTTP/1.1
   Host: api.dingtalk.io
   x-acs-dingtalk-access-token: {ACCESS_TOKEN}
   Content-Type: application/json
   
   {
     "roleId": "MANAGER",
     "members": [
       { "type": "USER", "id": "employee userId" }
     ]
   }
   

​

Scenario 3: Revoke a member’s Knowledge Base access

1. Confirm the role currently held by the member. Call the Get permission list API to retrieve the member’s current role (roleId). The role specified for removal must match the actual role held.
2. Call the Delete permissions API.

   Note: The roleId must match the role actually held by the member; otherwise, the operation is invalid. The OWNER role cannot be removed.

   POST /v2.0/storage/spaces/dentries/{dentryUuid}/permissions/remove?unionId={operator unionId} HTTP/1.1
   Host: api.dingtalk.io
   x-acs-dingtalk-access-token: {ACCESS_TOKEN}
   Content-Type: application/json
   
   {
     "roleId": "EDITOR",
     "members": [
       { "type": "USER", "id": "employee userId" }
     ]
   }
   

​

Scenario 4: Make the Knowledge Base accessible to all employees

Note: After ORG authorization, all employees in the organization can access the Knowledge Base with the specified role. ORG type members do not appear in the member list query results. To revoke access for all employees, call the remove API in the same way and pass ORG as the type.

POST /v2.0/storage/spaces/dentries/{dentryUuid}/permissions?unionId={operator unionId} HTTP/1.1
Host: api.dingtalk.io
x-acs-dingtalk-access-token: {ACCESS_TOKEN}
Content-Type: application/json

{
  "roleId": "READER",
  "members": [
    { "type": "ORG" }
  ]
}

​

Scenario 5: Query the current member list of a Knowledge Base

POST /v2.0/storage/spaces/dentries/{dentryUuid}/permissions/query?unionId={operator unionId} HTTP/1.1
Host: api.dingtalk.io
x-acs-dingtalk-access-token: {ACCESS_TOKEN}
Content-Type: application/json

{
  "option": {
    "maxResults": 30,
    "filterRoleIds": ["MANAGER", "EDITOR"]
  }
}

​

Notes

• The operator must have OWNER or MANAGER permissions on the Knowledge Base; otherwise, the API returns an insufficient permissions error.
• The OWNER role cannot be added or removed via the API. The Knowledge Base creator is the owner by default.
• When removing a member, the roleId must match the role actually held by the member; otherwise, the operation is invalid.
• A single request supports up to 30 members in the members list. Split into multiple calls if you exceed this limit.