# How to Manage Team Roles and Permissions in TencentDB Agent Memory

> Learn to manage team roles and permissions in TencentDB Agent Memory using its RBAC system. Control access with admin, member, and reviewer roles and ACL rules.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-27

---

**TencentDB Agent Memory implements a fine-grained role-based access control (RBAC) system that defines three distinct TeamRole levels (admin, member, reviewer) and six Permission types, enforcing access through ACL rules stored in the metadata service.**

Managing team roles and permissions in TencentDB Agent Memory relies on a type-safe RBAC model defined in the TypeScript SDK's metadata definitions. The system distinguishes between role assignment (who belongs to a team) and permission grants (what actions users can perform on specific assets), with all enforcement handled by the V3 metadata service according to the logic implemented in TencentCloud/TencentDB-Agent-Memory.

## Understanding the RBAC Type System

The foundation of access control resides in [`sdk/memory-core/typescript/src/v3/metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/metadata-types.ts), which exports the enums and interfaces used across the platform's security layer.

### TeamRole and Permission Definitions

According to the source code at line 8 of [`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts), the **TeamRole** enum restricts users to one of three hierarchical levels:

- `admin`: Full team management capabilities, including role assignment
- `member`: Standard participation rights for collaboration
- `reviewer`: Read-only access with evaluation privileges

The **Permission** enum (line 17) defines six possible actions: `read`, `write`, `delete`, `assign`, `share`, and `use`. These permissions are not assigned directly to users; instead, they are bound to assets through Access Control Lists (ACLs) that reference these enum values.

### ACL Subject Types and Entities

Line 18 of [`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts) defines **AclSubjectType**, which determines the scope of an ACL rule. A subject can be a concrete user ID, a team role (applying to all members holding that role), or an agent entity.

The **TeamMemberEntity** interface (line 103) represents the database record linking users to teams, storing the assigned `TeamRole` alongside membership metadata. This entity is the source of truth for the metadata service when resolving a caller's effective privileges.

## Managing Team Members

Team lifecycle operations flow through the V3 REST API, with SDK methods in [`client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts) and [`client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.py) providing typed wrappers around these endpoints.

### Creating Teams and Assigning Initial Roles

When you invoke `client.createTeam()`, the authenticated caller automatically receives the `admin` role for that team. To onboard additional users, call `addTeamMember` with the `role` parameter set to your desired `TeamRole` value.

```typescript
// Create a team - creator becomes admin automatically
const team = await client.createTeam({
  name: "Analytics Team",
  description: "Team for data-driven insights",
});
console.log(`Team created, ID = ${team.team_id}`);

// Add a member with specific role
await client.addTeamMember({
  team_id: team.team_id,
  user_id: "u-12345",
  role: "member",  // Valid options: admin | member | reviewer
});

```

Python implementation using the generated client:

```python

# Create a team

team = client.create_team(name="Analytics Team", description="Data-driven insights")

# Add a member as a reviewer

client.add_team_member(
    team_id=team.team_id,
    user_id="u-12345",
    role="reviewer"
)

```

### Updating Member Roles

Role modifications require the caller to hold the `admin` role. The `updateTeamMember` method (wrapping `PATCH /team/member/{id}`) modifies the `TeamMemberEntity.role` property in the metadata store.

```typescript
// Promote a member to admin - requires caller to be admin
await client.updateTeamMember({
  member_id: "tm-67890",
  role: "admin",
});

```

```python

# Promote to admin

client.update_team_member(member_id="tm-67890", role="admin")

```

## Configuring Asset-Level Permissions

While role management controls team membership, **permission management** occurs through ACL entries attached to assets such as skills, agents, or code graphs. The metadata service persists these rules and evaluates them against incoming requests.

### Granting Permissions via ACL Rules

Use `updateAssetAcl` to bind permissions to subjects. Setting `subject_type` to `"team_role"` applies the rule broadly to all members holding that role, as implemented in the V3 endpoints defined in [`openapi.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/openapi.yaml).

```typescript
await client.updateAssetAcl({
  asset_id: "skill-abcde",
  acl: [
    {
      subject_type: "team_role",
      subject_id: "member",
      permission: "read",
      effect: "allow",
    },
    {
      subject_type: "team_role",
      subject_id: "admin",
      permission: "write",
      effect: "allow",
    },
  ],
});

```

Python equivalent:

```python
client.update_asset_acl(
    asset_id="codegraph-xyz",
    acl=[
        {
            "subject_type": "team_role",
            "subject_id": "member",
            "permission": "read",
            "effect": "allow",
        },
        {
            "subject_type": "team_role",
            "subject_id": "admin",
            "permission": "write",
            "effect": "allow",
        },
    ],
)

```

## Server-Side Validation Flow

When a request reaches the metadata service, the core server performs a three-step validation process:

1. **Role Resolution**: Retrieves the caller's `TeamRole` from `TeamMemberEntity` records for the target team
2. **ACL Retrieval**: Fetches ACL entries matching the requested asset and `AclSubjectType` (user, team role, or agent)
3. **Effect Evaluation**: Checks if the requested `Permission` is present with an `allow` effect and no overriding `deny` effect

If the caller lacks the required permission, the server returns HTTP `403 Forbidden`. This enforcement applies uniformly across all V3 endpoints, ensuring that both SDK calls and direct REST API usage adhere to the same security policies defined in the source type definitions.

## Summary

- **TeamRole hierarchy**: The system supports `admin`, `member`, and `reviewer` roles defined in [`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts) (line 8), with no implicit permissions attached to these labels by default
- **Permission granularity**: Six distinct permissions (`read`, `write`, `delete`, `assign`, `share`, `use`) control asset access (line 17) and must be explicitly granted via ACLs
- **Role assignment**: Use `addTeamMember` and `updateTeamMember` (wrapping `POST /team/member/add` and `PATCH /team/member/{id}`) to manage team composition; only admins can modify existing member roles
- **Permission grants**: Configure ACL rules via `updateAssetAcl`, binding `Permission` values to `AclSubjectType` targets to enforce fine-grained access control
- **Enforcement**: The metadata service validates every request against the caller's resolved role and asset ACLs, returning `403` for unauthorized operations

## Frequently Asked Questions

### What are the default permissions for each TeamRole in TencentDB Agent Memory?

The RBAC system does not hard-code implicit permissions for roles. Instead, `admin`, `member`, and `reviewer` function as labels used in ACL rules. By default, new assets have no ACL entries, meaning only the creating user (implicitly granted admin rights) can access them until explicit `allow` rules are created for specific `TeamRole` values in the metadata store.

### Can a user hold different roles in different teams?

Yes. The `TeamMemberEntity` structure (line 103 in [`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts)) binds a `TeamRole` to a specific team membership record. A user can be an `admin` in one team and a `reviewer` in another, with the server resolving the appropriate role context based on the team ID present in the request path.

### How do I restrict a specific agent from accessing an asset while allowing team members?

Set the `subject_type` to `"agent"` in the ACL entry with an `effect` of `"deny"` for that specific agent ID, while maintaining `allow` entries for `team_role` subjects. The server evaluates deny rules before allow rules, ensuring the explicit restriction takes precedence over role-based grants defined in the metadata service.

### Where are the OpenAPI specifications for team management endpoints located?

The REST API contracts are defined in [`MemoryKnowledge/openapi.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/openapi.yaml) at the repository root. This file describes the HTTP endpoints for `POST /team/member/add`, `PATCH /team/member/{id}`, and ACL management operations that the TypeScript and Python SDKs wrap with methods like `addTeamMember` and `updateAssetAcl`.