用户与权限 GraphQL API
🌐 Users & Permissions GraphQL API
Page summary:
“用户与权限”功能提供用于身份验证、用户管理和基于角色的访问的 GraphQL 查询和变更。
此页面记录了用户与权限功能提供的所有 GraphQL 查询和变更。有关配置详情,请参见主 用户与权限页面。
🌐 This page documents all GraphQL queries and mutations provided by the Users & Permissions feature. For configuration details, see the main Users & Permissions page.
身份验证
🌐 Authentication
身份验证变更处理登录、注册和密码管理。公共变更不需要授权头。
🌐 Authentication mutations handle login, registration, and password management. Public mutations do not require an Authorization header.
登录
🌐 Login
login 突变用于验证用户并返回 JWT:
🌐 The login mutation authenticates a user and returns a JWT:
mutation {
login(input: { identifier: "user@example.com", password: "yourPassword" }) {
jwt
user {
id
documentId
username
email
confirmed
blocked
}
}
}
输入类型 UsersPermissionsLoginInput:
🌐 Input type UsersPermissionsLoginInput:
identifier(字符串!):电子邮件或用户名password(字符串!)provider(字符串,默认为 "local")
返回 UsersPermissionsLoginPayload:jwt(字符串),user(UsersPermissionsMe)
🌐 Returns UsersPermissionsLoginPayload: jwt (String), user (UsersPermissionsMe)
认证:公开
🌐 Auth: Public
注册
🌐 Register
register 突变会创建一个新的用户账户并返回一个 JWT:
🌐 The register mutation creates a new user account and returns a JWT:
mutation {
register(input: { username: "newuser", email: "new@example.com", password: "Password123!" }) {
jwt
user {
id
documentId
username
email
}
}
}
输入类型 UsersPermissionsRegisterInput:
🌐 Input type UsersPermissionsRegisterInput:
username(字符串!)email(字符串!)password(字符串!)
返回 UsersPermissionsLoginPayload
🌐 Returns UsersPermissionsLoginPayload
认证:公开
🌐 Auth: Public
默认情况下仅接受 username、email 和 password。其他字段需要 register.allowedFields 配置。
🌐 Only username, email, and password are accepted by default. Additional fields require register.allowedFields configuration.
忘记密码
🌐 Forgot password
forgotPassword 突变向用户发送密码重置电子邮件:
🌐 The forgotPassword mutation sends a password reset email to the user:
mutation {
forgotPassword(email: "user@example.com") {
ok
}
}
输入:email(字符串!),作为直接参数传递,而不是封装在输入类型中。
🌐 Input: email (String!), passed as a direct argument, not wrapped in an input type.
返回 UsersPermissionsPasswordPayload:ok(布尔值!)
🌐 Returns UsersPermissionsPasswordPayload: ok (Boolean!)
认证:公开
🌐 Auth: Public
重置密码
🌐 Reset password
resetPassword 突变使用通过电子邮件收到的令牌设置新密码:
🌐 The resetPassword mutation sets a new password using the token received by email:
mutation {
resetPassword(code: "resetTokenFromEmail", password: "NewPassword123!", passwordConfirmation: "NewPassword123!") {
jwt
user {
id
username
email
}
}
}
输入(直接参数):
🌐 Input (direct arguments):
code(字符串!):从电子邮件重置令牌password(字符串!)passwordConfirmation(字符串!)
返回 UsersPermissionsLoginPayload
🌐 Returns UsersPermissionsLoginPayload
认证:公开
🌐 Auth: Public
更改密码
🌐 Change password
changePassword 突变会更新当前已认证用户的密码:
🌐 The changePassword mutation updates the password for the currently authenticated user:
mutation {
changePassword(currentPassword: "OldPassword123!", password: "NewPassword456!", passwordConfirmation: "NewPassword456!") {
jwt
user {
id
username
email
}
}
}
需要带有 Bearer 令牌的授权头。
🌐 Requires an Authorization header with a Bearer token.
输入(直接参数):
🌐 Input (direct arguments):
currentPassword(字符串!)password(字符串!)passwordConfirmation(字符串!)
返回 UsersPermissionsLoginPayload
🌐 Returns UsersPermissionsLoginPayload
认证:已认证
🌐 Auth: Authenticated
电子邮件确认
🌐 Email confirmation
emailConfirmation 突变使用通过电子邮件收到的令牌来确认用户的电子邮件地址:
🌐 The emailConfirmation mutation confirms a user's email address using the token received by email:
mutation {
emailConfirmation(confirmation: "confirmationTokenFromEmail") {
jwt
user {
id
username
email
confirmed
}
}
}
输入:confirmation(字符串!)
🌐 Input: confirmation (String!)
返回 UsersPermissionsLoginPayload
🌐 Returns UsersPermissionsLoginPayload
认证:公开
🌐 Auth: Public
与 REST 等价方法(会重定向)不同,GraphQL 变更会直接返回 JWT 和用户对象。
🌐 Unlike the REST equivalent (which redirects), the GraphQL mutation returns a JWT and user object directly.
用户查询和变更
🌐 User queries and mutations
这些操作用于检索和管理用户记录。它们需要为请求用户的角色启用相应的权限。
🌐 These operations retrieve and manage user records. They require the corresponding permission to be enabled for the requesting user's role.
用户和角色变更(updateUsersPermissionsUser、deleteUsersPermissionsUser、updateUsersPermissionsRole、deleteUsersPermissionsRole)接受数字数据库 id 作为 id 参数,与它们的 REST 等价物使用相同的值。documentId 在响应中作为参考被暴露,但不被接受作为变更参数。
🌐 User and role mutations (updateUsersPermissionsUser, deleteUsersPermissionsUser, updateUsersPermissionsRole, deleteUsersPermissionsRole) accept the numeric database id as the id argument, the same value used by their REST equivalents. The documentId is exposed in the response for reference but is not accepted as the mutation argument.
获取已认证的用户(我查询)
🌐 Get authenticated user (me query)
me 查询返回当前经过身份验证的用户的个人资料:
🌐 The me query returns the profile of the currently authenticated user:
query {
me {
id
documentId
username
email
confirmed
blocked
role {
id
name
description
type
}
}
}
需要授权头。返回 UsersPermissionsMe 类型。
🌐 Requires an Authorization header. Returns UsersPermissionsMe type.
创建用户
🌐 Create a user
createUsersPermissionsUser 突变会创建一个新的用户记录:
🌐 The createUsersPermissionsUser mutation creates a new user record:
mutation {
createUsersPermissionsUser(data: { username: "newuser", email: "new@example.com", password: "Password123!" }) {
data {
documentId
username
email
}
}
}
输入:UsersPermissionsUserInput(从用户内容类型模式自动生成,并添加了 password 字段)
🌐 Input: UsersPermissionsUserInput (auto-generated from User content-type schema, with password field added)
权限:需要 plugin::users-permissions.user.create 权限
🌐 Auth: Requires plugin::users-permissions.user.create permission
更新用户
🌐 Update a user
updateUsersPermissionsUser 突变更新现有的用户记录:
🌐 The updateUsersPermissionsUser mutation updates an existing user record:
mutation {
updateUsersPermissionsUser(id: "1", data: { username: "updatedname" }) {
data {
documentId
username
email
}
}
}
权限:需要 plugin::users-permissions.user.update 权限
🌐 Auth: Requires plugin::users-permissions.user.update permission
删除用户
🌐 Delete a user
deleteUsersPermissionsUser 突变会删除一个用户记录:
🌐 The deleteUsersPermissionsUser mutation removes a user record:
mutation {
deleteUsersPermissionsUser(id: "1") {
data {
documentId
username
}
}
}
权限:需要 plugin::users-permissions.user.destroy 权限
🌐 Auth: Requires plugin::users-permissions.user.destroy permission
角色修改
🌐 Role mutations
角色变更管理终端用户角色。它们在成功时返回 { ok: true }(不是角色数据)。
🌐 Role mutations manage end-user roles. They return { ok: true } on success (not the role data).
创建一个角色
🌐 Create a role
createUsersPermissionsRole 突变创建了一个新的角色:
🌐 The createUsersPermissionsRole mutation creates a new role:
mutation {
createUsersPermissionsRole(data: { name: "Editor", description: "Can edit content" }) {
ok
}
}
权限:需要 plugin::users-permissions.role.createRole 权限
🌐 Auth: Requires plugin::users-permissions.role.createRole permission
更新角色
🌐 Update a role
updateUsersPermissionsRole 突变会更新现有角色:
🌐 The updateUsersPermissionsRole mutation updates an existing role:
mutation {
updateUsersPermissionsRole(id: "1", data: { name: "Senior Editor", description: "Can edit and publish" }) {
ok
}
}
权限:需要 plugin::users-permissions.role.updateRole 权限
🌐 Auth: Requires plugin::users-permissions.role.updateRole permission
删除角色
🌐 Delete a role
deleteUsersPermissionsRole 突变移除了一个角色:
🌐 The deleteUsersPermissionsRole mutation removes a role:
mutation {
deleteUsersPermissionsRole(id: "3") {
ok
}
}
权限:需要 plugin::users-permissions.role.deleteRole 权限
🌐 Auth: Requires plugin::users-permissions.role.deleteRole permission
公共角色无法被删除。
🌐 The Public role cannot be deleted.
会话管理
🌐 Session management
会话管理操作(令牌刷新和注销)仅通过 REST API 提供。这些端点没有 GraphQL 等价功能。
🌐 Session management operations (token refresh and logout) are only available through the REST API. There are no GraphQL equivalents for these endpoints.
类型参考
🌐 Types reference
本节列出了在用户与权限操作中使用的关键 GraphQL 类型。
🌐 This section lists the key GraphQL types used across Users & Permissions operations.
输入类型
🌐 Input types
| 类型 | 字段 | 使用者 |
|---|---|---|
UsersPermissionsLoginInput | identifier (字符串!), password (字符串!), provider (字符串) | login 变更 |
UsersPermissionsRegisterInput | username (字符串!), email (字符串!), password (字符串!) | register 变更 |
响应类型
🌐 Response types
| 类型 | 字段 | 使用者 |
|---|---|---|
UsersPermissionsLoginPayload | jwt (字符串), user (UsersPermissionsMe!) | login, register, resetPassword, changePassword, emailConfirmation |
UsersPermissionsPasswordPayload | ok (布尔值!) | forgotPassword |
UsersPermissionsMe | id (ID!), documentId (ID!), username (字符串!), email (字符串), confirmed (布尔值), blocked (布尔值), role (UsersPermissionsMeRole) | me 查询, 嵌套在登录负载中 |
UsersPermissionsMeRole | id (ID!), name (字符串!), description (字符串), type (字符串) | 嵌套在 UsersPermissionsMe 中 |