用户与权限 REST API

🌐 Users & Permissions REST API

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

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

🌐 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.

所有端点都使用 /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

身份验证端点处理登录、注册和密码管理。这些端点大多数默认是公开的，不需要 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

POST /api/auth/local

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

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

示例请求：登录

terminal
curl -X POST http://localhost:1337/api/auth/local \
  -H "Content-Type: application/json" \
  -d '{"identifier": "user@example.com", "password": "yourPassword"}'

Example response

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "documentId": "x74detpqybxw0bn6ormua5g2",
    "username": "testuser1",
    "email": "user@example.com",
    "provider": "local",
    "confirmed": true,
    "blocked": false,
    "createdAt": "2024-03-15T10:00:00.000Z",
    "updatedAt": "2024-03-15T10:00:00.000Z",
    "publishedAt": "2024-03-15T10:00:00.000Z"
  }
}

可能的错误：

🌐 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

POST /api/auth/local/register

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

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

示例请求：注册

terminal
curl -X POST http://localhost:1337/api/auth/local/register \
  -H "Content-Type: application/json" \
  -d '{"username": "newuser", "email": "newuser@example.com", "password": "Password123!"}'

Example response

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 2,
    "documentId": "xjpaytstw1gm7wdfoc6c2k13",
    "username": "newuser",
    "email": "newuser@example.com",
    "provider": "local",
    "confirmed": true,
    "blocked": false,
    "createdAt": "2024-03-15T10:00:00.000Z",
    "updatedAt": "2024-03-15T10:00:00.000Z",
    "publishedAt": "2024-03-15T10:00:00.000Z"
  }
}

Note

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

🌐 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 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

POST /api/auth/forgot-password

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

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

示例请求：忘记密码

terminal
curl -X POST http://localhost:1337/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Example response

{
  "ok": true
}

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

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.

示例请求：重置密码

terminal
curl -X POST http://localhost:1337/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{"code": "resetTokenFromEmail", "password": "NewPassword123!", "passwordConfirmation": "NewPassword123!"}'

Example response

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "documentId": "x74detpqybxw0bn6ormua5g2",
    "username": "testuser1",
    "email": "user@example.com",
    "provider": "local",
    "confirmed": true,
    "blocked": false,
    "createdAt": "2024-03-15T10:00:00.000Z",
    "updatedAt": "2024-03-15T10:00:00.000Z",
    "publishedAt": "2024-03-15T10:00:00.000Z"
  }
}

可能的错误：

🌐 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

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.

示例请求：更改密码

terminal
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!"}'

Example response

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "documentId": "x74detpqybxw0bn6ormua5g2",
    "username": "testuser1",
    "email": "user@example.com",
    "provider": "local",
    "confirmed": true,
    "blocked": false,
    "createdAt": "2024-03-15T10:00:00.000Z",
    "updatedAt": "2024-03-15T10:00:00.000Z",
    "publishedAt": "2024-03-15T10:00:00.000Z"
  }
}

可能的错误：

🌐 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

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).

示例请求：电子邮件确认

terminal
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

POST /api/auth/send-email-confirmation

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

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

示例请求：发送电子邮件确认

terminal
curl -X POST http://localhost:1337/api/auth/send-email-confirmation \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Example response

{
  "email": "user@example.com",
  "sent": true
}

可能的错误：

🌐 Possible errors:

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

此端点有速率限制。

🌐 This endpoint is rate limited.

提供者身份验证

🌐 Provider authentication

GET /api/connect/:provider

将用户重定向到第三方提供商的登录页面（例如，Google、GitHub、Discord）。用提供商名称替换 :provider。有关配置说明，请参见设置提供商。

🌐 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 for configuration instructions.

提供者回调

🌐 Provider callback

GET /api/auth/:provider/callback

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

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

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

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

会话管理

🌐 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

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).

示例请求：刷新令牌

terminal
curl -X POST http://localhost:1337/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "yourRefreshToken"}'

Example response

{
  "jwt": "newAccessToken",
  "refreshToken": "newRefreshToken"
}

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

POST /api/auth/logout

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

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

示例请求：注销

terminal
curl -X POST http://localhost:1337/api/auth/logout \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example response

{
  "ok": true
}

用户

🌐 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).

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 /api/users/me

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

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

示例请求：获取当前用户

terminal
curl http://localhost:1337/api/users/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example response

{
  "id": 1,
  "documentId": "x74detpqybxw0bn6ormua5g2",
  "username": "testuser1",
  "email": "user@example.com",
  "provider": "local",
  "confirmed": true,
  "blocked": false,
  "createdAt": "2024-03-15T10:00:00.000Z",
  "updatedAt": "2024-03-15T10:00:00.000Z",
  "publishedAt": "2024-03-15T10:00:00.000Z"
}

列出用户

🌐 List users

GET /api/users

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

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

示例请求：列出用户

terminal
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 /api/users/:id

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

🌐 Returns a single user by their integer id.

示例请求：获取用户

terminal
curl http://localhost:1337/api/users/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

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

🌐 Example response (200): A user object.

计算用户数

🌐 Count users

GET /api/users/count

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

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

示例请求：计算用户

terminal
curl http://localhost:1337/api/users/count \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example response

创建用户

🌐 Create a user

POST /api/users

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

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

示例请求：创建一个用户

terminal
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

PUT /api/users/:id

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

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

示例请求：更新用户

terminal
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:

{
  "role": "x74detpqybxw0bn6ormua5g2"  // role documentId (shorthand)
}

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

{
  "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 /api/users/:id

通过其整数 id 删除用户。

🌐 Deletes a user by their integer id.

示例请求：删除用户

terminal
curl -X DELETE http://localhost:1337/api/users/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

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

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

角色

🌐 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

GET /api/users-permissions/roles

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

🌐 Returns all available roles with user counts.

示例请求：列出角色

terminal
curl http://localhost:1337/api/users-permissions/roles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example response

{
  "roles": [
    {
      "id": 1,
      "documentId": "abcdefghijklmnop12345678",
      "name": "Authenticated",
      "description": "Default role given to authenticated user.",
      "type": "authenticated",
      "createdAt": "2024-03-15T10:00:00.000Z",
      "updatedAt": "2024-03-15T10:00:00.000Z",
      "publishedAt": "2024-03-15T10:00:00.000Z",
      "nb_users": 2
    },
    {
      "id": 2,
      "documentId": "qrstuvwxyzabcdef98765432",
      "name": "Public",
      "description": "Default role given to unauthenticated user.",
      "type": "public",
      "createdAt": "2024-03-15T10:00:00.000Z",
      "updatedAt": "2024-03-15T10:00:00.000Z",
      "publishedAt": "2024-03-15T10:00:00.000Z",
      "nb_users": 0
    }
  ]
}

获得一个角色

🌐 Get a role

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

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

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

示例请求：获取一个角色

terminal
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

POST /api/users-permissions/roles

创建一个新角色。

🌐 Creates a new role.

示例请求：创建一个角色

terminal
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"}'

Example response

{
  "ok": true
}

更新角色

🌐 Update a role

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

更新现有角色。

🌐 Updates an existing role.

示例请求：更新角色

terminal
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"}'

Example response

{
  "ok": true
}

删除角色

🌐 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.

示例请求：删除一个角色

terminal
curl -X DELETE http://localhost:1337/api/users-permissions/roles/3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example response

{
  "ok": true
}

可能的错误：

🌐 Possible errors:

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

权限

🌐 Permissions

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

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

列出权限

🌐 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.

示例请求：列出权限

terminal
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.

身份验证​

登录​

注册​

忘记密码​

重置密码​

更改密码​

电子邮件确认​

发送电子邮件确认​

提供者身份验证​

提供者回调​

会话管理​

刷新令牌​

登出​

用户​

获取当前用户​

列出用户​

获取用户​

计算用户数​

创建用户​

更新用户​

删除用户​

角色​

列出角色​

获得一个角色​

创建一个角色​

更新角色​

删除角色​

权限​

列出权限​

身份验证

登录

注册

忘记密码

重置密码

更改密码

电子邮件确认

发送电子邮件确认

提供者身份验证

提供者回调

会话管理

刷新令牌

登出

用户

获取当前用户

列出用户

获取用户

计算用户数

创建用户

更新用户

删除用户

角色

列出角色

获得一个角色

创建一个角色

更新角色

删除角色

权限

列出权限