---
title: RBAC API | 角色权限管理接口 - MengStack官方文档
---

# RBAC 接口

所有接口需要认证，并携带 `X-Tenant-ID` 头。

## 列出权限

**`GET /api/v1/rbac/permissions`**

### 查询参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `module` | string | 否 | 按模块筛选 |

### 响应

```json
{
  "code": 0,
  "data": [
    {
      "id": 1,
      "code": "auth:user:read",
      "name": "查看用户",
      "module": "auth",
      "description": "查看用户列表和详情"
    }
  ]
}
```

---

## 创建角色

**`POST /api/v1/rbac/roles`**

### 请求体

```json
{
  "name": "editor",
  "description": "内容编辑者"
}
```

| 字段 | 类型 | 必填 |
|------|------|------|
| `name` | string | 是 |
| `description` | string | 否 |

### 响应

返回 `RoleDTO`（含 `permissions` 数组）。

### 错误

| 状态码 | 说明 |
|--------|------|
| 400 | 参数校验失败 |
| 409 | 角色名已存在 |

---

## 列出角色

**`GET /api/v1/rbac/roles`**

### 响应

```json
{
  "code": 0,
  "data": [
    {
      "id": 1,
      "tenant_id": "550e8400-...",
      "name": "admin",
      "description": "系统管理员",
      "is_system": true,
      "permissions": [...]
    }
  ]
}
```

---

## 获取角色详情

**`GET /api/v1/rbac/roles/:id`**

### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | int | 角色 ID |

### 响应

返回 `RoleDTO`。

---

## 更新角色

**`PUT /api/v1/rbac/roles/:id`**

### 请求体

```json
{
  "name": "senior-editoror",
  "description": "高级编辑"
}
```

| 字段 | 类型 | 必填 |
|------|------|------|
| `name` | string | 否 |
| `description` | string | 否 |

---

## 删除角色

**`DELETE /api/v1/rbac/roles/:id`**

### 错误

| 状态码 | 说明 |
|--------|------|
| 403 | 系统角色不可删除 |

---

## 设置角色权限

**`PUT /api/v1/rbac/roles/:id/permissions`**

### 请求体

```json
{
  "permission_ids": [1, 2, 3, 5]
}
```

覆盖该角色的全部权限。

---

## 获取角色权限

**`GET /api/v1/rbac/roles/:id/permissions`**

### 响应

返回 `PermissionDTO` 数组。

---

## 分配角色给用户

**`POST /api/v1/rbac/users/:userId/roles`**

### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `userId` | int | 用户 ID |

### 请求体

```json
{
  "role_id": 2
}
```

### 错误

| 状态码 | 说明 |
|--------|------|
| 409 | 用户已拥有该角色 |

---

## 移除用户角色

**`DELETE /api/v1/rbac/users/:userId/roles/:roleId`**

### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `userId` | int | 用户 ID |
| `roleId` | int | 角色 ID |

---

## 获取用户角色

**`GET /api/v1/rbac/users/:userId/roles`**

### 响应

返回 `RoleDTO` 数组，包含该用户在此租户下的所有角色及权限。