# 用户与权限 REST API

> Source: https://strapi.nodejs.cn/cms/features/users-permissions/rest-api

🌐 Users & Permissions REST API

“用户与权限”功能提供用于身份验证、用户管理、角色和权限的 REST API 端点。

“用户与权限”功能提供了一组用于身份验证、用户管理和角色/权限管理的 REST API 端点。这些端点与标准的内容类型 CRUD 端点是分开的，并且具有自己的响应格式。有关概览和配置选项，请参阅 [用户与权限介绍](/cms/features/users-permissions)。

🌐 The Users & Permissions feature exposes a set of REST API endpoints for authentication, user management, and role/permission management. These endpoints are separate from the standard content-type CRUD endpoints and have their own response shapes. For a general overview and configuration options, see the [Users & Permissions introduction](/cms/features/users-permissions).

所有端点都使用 `/api` 前缀。例如，如果你的 Strapi 服务器运行在 `http://localhost:1337`，登录端点是 `http://localhost:1337/api/auth/local`。

🌐 All endpoints use the `/api` prefix. For example, if your Strapi server runs at `http://localhost:1337`, the login endpoint is `http://localhost:1337/api/auth/local`.

## 身份验证 {#authentication}

🌐 Authentication

身份验证端点处理登录、注册和密码管理。这些端点大多数默认是公开的，不需要 Bearer 令牌。

🌐 Authentication endpoints handle login, registration, and password management. Most of these endpoints are public by default and do not require a Bearer token.

### 登录 {#login}

🌐 Login

`POST /api/auth/local`

使用用户的标识符（电子邮件或用户名）和密码进行身份验证，返回 JWT 和用户对象。

🌐 Authenticates a user with their identifier (email or username) and password, returning a JWT and the user object.

**示例请求：登录:**
```bash
curl -X POST http://localhost:1337/api/auth/local \
  -H "Content-Type: application/json" \
  -d '{"identifier": "user@example.com", "password": "yourPassword"}'
```

可能的错误：

🌐 Possible errors:

| 状态 | 信息 | 原因 |
|--------|---------|-------|
| 400 | `"Invalid identifier or password"` | 凭证错误 |
| 400 | `"Your account email is not confirmed"` | 需要电子邮件确认但未完成 |
| 400 | `"Your account has been blocked by an administrator"` | 账户被封禁 |

此端点有限流（默认：每5分钟5次请求）。

🌐 This endpoint is rate limited (default: 5 requests per 5 minutes).

### 注册 {#register}

🌐 Register

`POST /api/auth/local/register`

创建一个新的用户账户，并返回一个 JWT 以及用户对象。

🌐 Creates a new user account and returns a JWT along with the user object.

**示例请求：注册:**
```bash
curl -X POST http://localhost:1337/api/auth/local/register \
  -H "Content-Type: application/json" \
  -d '{"username": "newuser", "email": "newuser@example.com", "password": "Password123!"}'
```

:::note

默认情况下，请求体中只接受 `username`、`email` 和 `password`。要允许额外的字段（例如，你在用户内容类型中添加的 `fullName` 字段），你必须在 `register.allowedFields` 配置中明确列出它们。详情请参见 [注册配置](/cms/features/users-permissions#registration-configuration)。

🌐 Only `username`, `email`, and `password` are accepted in the request body by default. To allow additional fields (e.g., a `fullName` field you added to the User content-type), you must explicitly list them in the `register.allowedFields` configuration. See [Registration configuration](/cms/features/users-permissions#registration-configuration) for details.

启用电子邮件确认时，响应仅包含用户对象，而不包含 JWT。用户必须确认他们的电子邮件后才能登录。

🌐 When email confirmation is enabled, the response contains only the user object without a JWT. The user must confirm their email before they can log in.

新注册的用户会被分配默认角色，除非在 设置 > 用户与权限 > 高级设置 中更改，否则默认角色为“已认证”.

🌐 The newly registered user is assigned the default role, which is "Authenticated" unless changed in Settings > Users & Permissions > Advanced Settings.

:::

可能的错误：

🌐 Possible errors:

| 状态 | 信息 | 原因 |
|--------|---------|-------|
| 400 | `"Email or Username are already taken"` | 邮箱或用户名重复 |
| 400 | `"Invalid parameters: fieldName"` | `allowedFields` 中未列出的额外字段 |
| 400 | `"Register action is currently disabled"` | 管理设置中禁用了注册 |

此端点有速率限制。

🌐 This endpoint is rate limited.

### 忘记密码 {#forgot-password}

🌐 Forgot password

`POST /api/auth/forgot-password`

向指定的地址发送密码重置电子邮件。需要配置电子邮件提供商。

🌐 Sends a password reset email to the specified address. Requires an email provider to be configured.

**示例请求：忘记密码:**
```bash
curl -X POST http://localhost:1337/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

:::note

这个端点总是返回 `{ "ok": true }`，无论电子邮件地址是否存在于系统中。这是有意为之，以防止用户枚举攻击。

🌐 This endpoint always returns `{ "ok": true }` regardless of whether the email address exists in the system. This is intentional to prevent user enumeration attacks.

:::

此端点有速率限制。

🌐 This endpoint is rate limited.

### 重置密码 {#reset-password}

🌐 Reset password

`POST /api/auth/reset-password`

使用通过电子邮件收到的令牌重置用户的密码。`code`、`password` 和 `passwordConfirmation` 字段都是必填的。

🌐 Resets a user's password using a token received by email. The `code`, `password`, and `passwordConfirmation` fields are all required.

**示例请求：重置密码:**
```bash
curl -X POST http://localhost:1337/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{"code": "resetTokenFromEmail", "password": "NewPassword123!", "passwordConfirmation": "NewPassword123!"}'
```

可能的错误：

🌐 Possible errors:

| 状态 | 消息 | 原因 |
|--------|---------|-------|
| 400 | `"passwordConfirmation is a required field"` | 缺少 `passwordConfirmation` |
| 400 | `"Passwords do not match"` | `password` 和 `passwordConfirmation` 不一致 |
| 400 | `"Incorrect code provided"` | 重置令牌无效或已过期 |

此端点有速率限制。

🌐 This endpoint is rate limited.

### 更改密码 {#change-password}

🌐 Change password

`POST /api/auth/change-password`

更改当前已认证用户的密码。需要一个有效的 Bearer 令牌。`currentPassword`、`password` 和 `passwordConfirmation` 字段都是必填的。

🌐 Changes the password for the currently authenticated user. Requires a valid Bearer token. The `currentPassword`, `password`, and `passwordConfirmation` fields are all required.

**示例请求：更改密码:**
```bash
curl -X POST http://localhost:1337/api/auth/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"currentPassword": "OldPassword123!", "password": "NewPassword456!", "passwordConfirmation": "NewPassword456!"}'
```

可能的错误：

🌐 Possible errors:

| 状态 | 消息 | 原因 |
|--------|---------|-------|
| 400 | `"passwordConfirmation is a required field"` | 缺少 `passwordConfirmation` |
| 400 | `"Passwords do not match"` | `password` 和 `passwordConfirmation` 不同 |
| 400 | `"The provided current password is invalid"` | 当前密码错误 |
| 400 | `"Your new password must be different than your current password"` | 重复使用相同密码 |

此端点有速率限制。

🌐 This endpoint is rate limited.

### 电子邮件确认 {#email-confirmation}

🌐 Email confirmation

`GET /api/auth/email-confirmation`

使用确认邮件中的令牌确认用户的电子邮件地址。

🌐 Confirms a user's email address using a token from the confirmation email.

查询参数：`confirmation`（在确认邮件中收到的令牌）。

🌐 Query parameter: `confirmation` (the token received in the confirmation email).

**示例请求：电子邮件确认:**
```bash
curl -G http://localhost:1337/api/auth/email-confirmation \
  --data-urlencode "confirmation=confirmationTokenHere"
```

确认电子邮件后，Strapi 会将用户重定向到在管理面板的 设置 > 用户与权限 > 高级设置 > "重定向 URL" 下配置的 URL。

🌐 After confirming the email, Strapi redirects the user to the URL configured in the admin panel under Settings > Users & Permissions > Advanced Settings > "Redirection url".

可能的错误：

🌐 Possible errors:

| 状态 | 消息 | 原因 |
|--------|---------|-------|
| 400 | `"confirmation is a required field"` | 缺少 `confirmation` 查询参数 |
| 400 | `"Invalid token"` | 确认令牌格式错误、已过期或已使用 |

### 发送电子邮件确认 {#send-email-confirmation}

🌐 Send email confirmation

`POST /api/auth/send-email-confirmation`

重新发送确认电子邮件给尚未确认其电子邮件地址的用户。

🌐 Resends the confirmation email to a user who has not yet confirmed their email address.

**示例请求：发送电子邮件确认:**
```bash
curl -X POST http://localhost:1337/api/auth/send-email-confirmation \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

可能的错误：

🌐 Possible errors:

| 状态 | 消息 | 原因 |
|--------|---------|-------|
| 400 | `"Already confirmed"` | 用户已确认其电子邮件 |
| 400 | `"User blocked"` | 账户被封锁 |

此端点有速率限制。

🌐 This endpoint is rate limited.

### 提供者身份验证 {#provider-authentication}

🌐 Provider authentication

`GET /api/connect/:provider`

将用户重定向到第三方提供商的登录页面（例如，Google、GitHub、Discord）。用提供商名称替换 `:provider`。有关配置说明，请参见 [设置提供商](/cms/configurations/users-and-permissions-providers)。

🌐 Redirects the user to a third-party provider's login page (e.g., Google, GitHub, Discord). Replace `:provider` with the provider name. See [Setting up providers](/cms/configurations/users-and-permissions-providers) for configuration instructions.

### 提供者回调 {#provider-callback}

🌐 Provider callback

`GET /api/auth/:provider/callback`

在用户通过第三方提供商进行身份验证后处理 OAuth 回调。成功时，返回与 [login](#login) 相同的响应格式（jwt + 用户）。

🌐 Handles the OAuth callback after the user authenticates with a third-party provider. On success, returns the same response shape as [login](#login) (jwt + user).

如果从提供者资料中派生的用户名已存在，将会自动生成一个唯一用户名以避免冲突。

🌐 If the username derived from the provider profile already exists, a unique username is generated automatically to avoid conflicts.

## 会话管理 {#session-management}

🌐 Session management

当会话管理启用时（在插件配置中为 `jwtManagement: 'refresh'`），这些额外的端点将可用。当默认的传统 JWT 模式处于活动状态时，它们会返回 404。

🌐 When session management is enabled (`jwtManagement: 'refresh'` in the plugin configuration), these additional endpoints become available. They return 404 when the default legacy JWT mode is active.

### 刷新令牌 {#refresh-token}

🌐 Refresh token

`POST /api/auth/refresh`

用刷新令牌交换新的访问令牌。旧的刷新令牌将失效，并返回一个新的刷新令牌（令牌轮换）。

🌐 Exchanges a refresh token for a new access token. The old refresh token is invalidated and a new one is returned (token rotation).

**示例请求：刷新令牌:**
```bash
curl -X POST http://localhost:1337/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "yourRefreshToken"}'
```

:::note

当在会话配置中启用 `httpOnly` 时，新的刷新令牌将被设置为 HTTP-only cookie，而不是包含在响应正文中。在这种情况下，响应仅包含 `{ "jwt": "newAccessToken" }`。

🌐 When `httpOnly` is enabled in the session configuration, the new refresh token is set as an HTTP-only cookie instead of being included in the response body. In that case, the response only contains `{ "jwt": "newAccessToken" }`.

:::

### 登出 {#logout}

🌐 Logout

`POST /api/auth/logout`

撤销经过身份验证的用户的所有会话。需要有效的 Bearer 令牌。

🌐 Revokes all sessions for the authenticated user. Requires a valid Bearer token.

**示例请求：注销:**
```bash
curl -X POST http://localhost:1337/api/auth/logout \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## 用户 {#users}

🌐 Users

用户管理端点处理终端用户记录的增删改查操作。每个端点都需要在管理员面板中为用户的角色启用相应的权限（设置 > 用户与权限 > 角色）。

🌐 User management endpoints handle CRUD operations on end-user records. Each endpoint requires the corresponding permission to be enabled for the user's role in the admin panel (Settings > Users & Permissions > Roles).

:::caution Response format

用户端点返回的是纯 JSON 对象（没有封装在 `data` 键中），与标准 Strapi 内容类型端点不同。

🌐 User endpoints return bare JSON objects (not wrapped in a `data` key), unlike standard Strapi content-type endpoints.

:::

### 获取当前用户 {#get-current-user}

🌐 Get current user

`GET /api/users/me`

返回与提供的 JWT 关联的用户。需要身份验证。

🌐 Returns the user associated with the provided JWT. Requires authentication.

**示例请求：获取当前用户:**
```bash
curl http://localhost:1337/api/users/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 列出用户 {#list-users}

🌐 List users

`GET /api/users`

返回用户列表。支持 `filters`、`sort` 和 `pagination` 查询参数。

🌐 Returns a list of users. Supports `filters`, `sort`, and `pagination` query parameters.

**示例请求：列出用户:**
```bash
curl http://localhost:1337/api/users \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

示例响应（200）：一组用户对象。

🌐 Example response (200): An array of user objects.

### 获取用户 {#get-a-user}

🌐 Get a user

`GET /api/users/:id`

通过他们的整数 `id` 返回单个用户。

🌐 Returns a single user by their integer `id`.

**示例请求：获取用户:**
```bash
curl http://localhost:1337/api/users/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

示例响应（200）：一个用户对象。

🌐 Example response (200): A user object.

### 计算用户数 {#count-users}

🌐 Count users

`GET /api/users/count`

返回用户的总数。支持 `filters` 查询参数。

🌐 Returns the total number of users. Supports the `filters` query parameter.

**示例请求：计算用户:**
```bash
curl http://localhost:1337/api/users/count \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 创建用户 {#create-a-user}

🌐 Create a user

`POST /api/users`

创建一个新用户。如果省略 `role`，将分配默认角色。

🌐 Creates a new user. If `role` is omitted, the default role is assigned.

**示例请求：创建一个用户:**
```bash
curl -X POST http://localhost:1337/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"username": "newuser", "email": "newuser@example.com", "password": "Password123!", "role": 1, "confirmed": true}'
```

示例响应 (201)：一个包含已填充角色的用户对象。

🌐 Example response (201): A user object with the populated role.

:::tip

`role` 字段既接受数字型 `id`（遗留）也接受 `documentId`（Strapi v5 规范）。示例：

🌐 The `role` field accepts both numeric `id` (legacy) and `documentId` (Strapi v5 convention). Examples:

- `"role": 1` — 数字 ID
- `"role": "x74detpqybxw0bn6ormua5g2"` — 文档ID

:::

### 更新用户 {#update-a-user}

🌐 Update a user

`PUT /api/users/:id`

更新现有用户。只包含你想要更改的字段。

🌐 Updates an existing user. Only include the fields you want to change.

**示例请求：更新用户:**
```bash
curl -X PUT http://localhost:1337/api/users/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"username": "updateduser"}'
```

示例响应 (200)：更新后的用户对象。

🌐 Example response (200): The updated user object.

可能的错误：

🌐 Possible errors:

| 状态 | 消息 | 原因 |
|--------|---------|-------|
| 404 | `"User not found"` | 没有具有给定 `id` 的用户 |
| 400 | `"Username already taken"` 或 `"Email already taken"` | 值重复 |

:::note Relation inputs support both `documentId` and numeric IDs

在更新用户时，包括 `role` 关系，你可以在关系负载中使用 `documentId`（推荐用于 Strapi 5）或数字 `id`：

🌐 When updating a user, including the `role` relation, you can use either `documentId` (recommended for Strapi 5) or numeric `id` in relation payloads:

```json
{
  "role": "x74detpqybxw0bn6ormua5g2"  // role documentId (shorthand)
}
```
or

```json
{
  "role": {
    "connect": ["x74detpqybxw0bn6ormua5g2"]  // role documentId (longhand)
  }
}
```
or

```json
{
  "role": 1  // numeric ID (legacy)
}
```
For custom relations, you can also use the longhand format. Both formats are accepted for backward compatibility.

:::

### 删除用户 {#delete-a-user}

🌐 Delete a user

`DELETE /api/users/:id`

通过其整数 `id` 删除用户。

🌐 Deletes a user by their integer `id`.

**示例请求：删除用户:**
```bash
curl -X DELETE http://localhost:1337/api/users/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

示例响应 (200)：被删除的用户对象。

🌐 Example response (200): The deleted user object.

## 角色 {#roles}

🌐 Roles

角色端点管理终端用户角色及其相关权限。这些端点使用 `/api/users-permissions/` 前缀，而不是内容类型端点使用的标准 `/api/` 前缀。

🌐 Role endpoints manage end-user roles and their associated permissions. These endpoints use the `/api/users-permissions/` prefix, not the standard `/api/` prefix used by content-type endpoints.

### 列出角色 {#list-roles}

🌐 List roles

`GET /api/users-permissions/roles`

返回所有可用角色及其用户数量。

🌐 Returns all available roles with user counts.

**示例请求：列出角色:**
```bash
curl http://localhost:1337/api/users-permissions/roles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 获得一个角色 {#get-a-role}

🌐 Get a role

`GET /api/users-permissions/roles/:id`

通过 `id` 返回单个角色，包括其完整的权限树。

🌐 Returns a single role by `id`, including its full permissions tree.

**示例请求：获取一个角色:**
```bash
curl http://localhost:1337/api/users-permissions/roles/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

示例响应 (200)：一个形式为 `{ "role": { ... } }` 的对象，其中角色包含一个嵌套的 `permissions` 结构，将插件映射到控制器再映射到操作。

🌐 Example response (200): An object of the form `{ "role": { ... } }`, where the role contains a nested `permissions` structure mapping plugins to controllers to actions.

### 创建一个角色 {#create-a-role}

🌐 Create a role

`POST /api/users-permissions/roles`

创建一个新角色。

🌐 Creates a new role.

**示例请求：创建一个角色:**
```bash
curl -X POST http://localhost:1337/api/users-permissions/roles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"name": "Editor", "description": "Can edit content", "type": "editor"}'
```

### 更新角色 {#update-a-role}

🌐 Update a role

`PUT /api/users-permissions/roles/:id`

更新现有角色。

🌐 Updates an existing role.

**示例请求：更新角色:**
```bash
curl -X PUT http://localhost:1337/api/users-permissions/roles/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"description": "Updated description"}'
```

### 删除角色 {#delete-a-role}

🌐 Delete a role

`DELETE /api/users-permissions/roles/:id`

通过 `id` 删除一个角色。公共角色无法删除。当一个角色被删除时，分配给该角色的用户将被重新分配到公共角色。

🌐 Deletes a role by `id`. The Public role cannot be deleted. When a role is deleted, users assigned to it are reassigned to the Public role.

**示例请求：删除一个角色:**
```bash
curl -X DELETE http://localhost:1337/api/users-permissions/roles/3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

可能的错误：

🌐 Possible errors:

| 状态 | 消息 | 原因 |
|--------|---------|-------|
| 400 | `"Cannot delete public role"` | 尝试删除公共角色 |

## 权限 {#permissions}

🌐 Permissions

权限端点返回完整的权限树，显示所有插件和内容类型中可用的操作。

🌐 The permissions endpoint returns the complete permission tree, showing which actions are available across all plugins and content-types.

### 列出权限 {#list-permissions}

🌐 List permissions

`GET /api/users-permissions/permissions`

返回一个嵌套对象，将每个插件名称映射到一个 `controllers` 对象，该对象本身将控制器名称映射到动作。

🌐 Returns a nested object mapping each plugin name to a `controllers` object, which itself maps controller names to actions.

**示例请求：列出权限:**
```bash
curl http://localhost:1337/api/users-permissions/permissions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

示例响应 (200)：一个嵌套的 `permissions` 对象，其中顶层键是插件名称，每个插件包含一个 `controllers` 对象，其键是控制器名称，每个控制器映射到具有其 `enabled` 状态和 `policy` 信息的动作。

🌐 Example response (200): A nested `permissions` object where top-level keys are plugin names, each containing a `controllers` object whose keys are controller names, and each controller maps to actions with their `enabled` status and `policy` information.