用户与权限 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.
curl -X POST http://localhost:1337/api/auth/local \
-H "Content-Type: application/json" \
-d '{"identifier": "user@example.com", "password": "yourPassword"}'
{
"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.
curl -X POST http://localhost:1337/api/auth/local/register \
-H "Content-Type: application/json" \
-d '{"username": "newuser", "email": "newuser@example.com", "password": "Password123!"}'
{
"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"
}
}
默认情况下,请求体中只接受 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.
curl -X POST http://localhost:1337/api/auth/forgot-password \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com"}'
{
"ok": true
}
这个端点总是返回 { "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.
curl -X POST http://localhost:1337/api/auth/reset-password \
-H "Content-Type: application/json" \
-d '{"code": "resetTokenFromEmail", "password": "NewPassword123!", "passwordConfirmation": "NewPassword123!"}'
{
"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.
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!"}'
{
"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).
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.
curl -X POST http://localhost:1337/api/auth/send-email-confirmation \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com"}'
{
"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).
curl -X POST http://localhost:1337/api/auth/refresh \
-H "Content-Type: application/json" \
-d '{"refreshToken": "yourRefreshToken"}'
{
"jwt": "newAccessToken",
"refreshToken": "newRefreshToken"
}
当在会话配置中启用 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" }.
列出会话
🌐 List sessions
GET /api/auth/sessions
返回已认证用户的活跃会话,当前会话排在最前,其它会话按最近使用到最久未使用排序。需要有效的Bearer令牌。
🌐 Returns the active sessions of the authenticated user, with the current session first and the other sessions from the most to the least recently used. Requires a valid Bearer token.
curl http://localhost:1337/api/auth/sessions \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
{
"data": [
{
"id": "session-current",
"deviceId": "device-a",
"deviceName": "Chrome",
"current": true,
"loginAt": "2026-06-10T08:00:00.000Z",
"lastActiveAt": "2026-06-11T10:00:00.000Z"
},
{
"id": "session-other",
"deviceId": "device-b",
"deviceName": "Safari",
"current": false,
"loginAt": "2026-06-09T08:00:00.000Z",
"lastActiveAt": "2026-06-10T09:00:00.000Z"
}
]
}
每次响应的会话包含以下字段:
🌐 Each session of the response contains the following fields:
| 字段 | 描述 |
|---|---|
id | 会话的标识符。 |
deviceId | (可选)与会话关联的设备标识符。 |
deviceName | (可选)设备名称,来源于登录时发送的用户代理。 |
current | 用于发送请求的会话的 true。 |
loginAt | (可选)登录日期,采用 ISO 8601 格式。 |
lastActiveAt | (可选)最新刷新令牌轮换的日期,采用 ISO 8601 格式。它不会在每次 API 请求时更新。 |
会话从不包含令牌,也不包含除会话和设备标识符之外的数据库标识符。
🌐 Sessions never include tokens, nor database identifiers other than the session and device identifiers.
可能的错误:
🌐 Possible errors:
| 状态 | 信息 | 原因 |
|---|---|---|
| 401 | "Missing authentication" | 缺少或无效的Bearer令牌 |
撤销会话
🌐 Revoke a session
DELETE /api/auth/sessions/:sessionId
撤销已认证用户的会话。需要有效的 Bearer 令牌。
🌐 Revokes a session of the authenticated user. Requires a valid Bearer token.
curl -X DELETE http://localhost:1337/api/auth/sessions/session-other \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
{
"data": {}
}
可能的错误:
🌐 Possible errors:
| 状态 | 信息 | 原因 |
|---|---|---|
| 401 | "Missing authentication" | 缺少或无效的 Bearer 令牌 |
| 404 | "Session not found" | 会话不存在或属于其他用户 |
登出
🌐 Logout
POST /api/auth/logout
撤销当前经过身份验证用户的会话。需要有效的Bearer令牌。
🌐 Revokes the current session of the authenticated user. Requires a valid Bearer token.
可选的请求主体扩大了撤销的范围:
🌐 The optional request body widens the scope of the revocation:
| 主体 | 已撤销的会话 |
|---|---|
{ "scope": "all" } | 用户的所有会话。 |
{ "deviceId": "device-a" } | 指定设备的所有会话。 |
当前会话是从请求上下文中读取的,然后从 cookie 或请求体的 refreshToken 属性中找到的刷新令牌中读取。如果无法识别当前会话,用户的所有会话都会被撤销。
🌐 The current session is read from the request context, then from the refresh token found in the cookie or in the refreshToken property of the request body. If the current session cannot be identified, all the sessions of the user are revoked.
curl -X POST http://localhost:1337/api/auth/logout \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
{
"ok": true
}
当会话配置中启用 httpOnly 时,刷新令牌的 Cookie 也会被清除。
🌐 When httpOnly is enabled in the session configuration, the refresh token cookie is also cleared.
用户
🌐 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).
用户端点返回的是纯 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.
curl http://localhost:1337/api/users/me \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
{
"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.
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.
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.
curl http://localhost:1337/api/users/count \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
42
创建用户
🌐 Create a user
POST /api/users
创建一个新用户。如果省略 role,将分配默认角色。
🌐 Creates a new user. If role is omitted, the default role is assigned.
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.
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.
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" | 值重复 |
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)
}
or
{
"role": {
"connect": ["x74detpqybxw0bn6ormua5g2"] // role documentId (longhand)
}
}
or
{
"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.
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.
curl http://localhost:1337/api/users-permissions/roles \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
{
"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