用户与权限 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.

Prerequisites

必须安装GraphQL 插件。

🌐 The GraphQL plugin must be installed.

身份验证

🌐 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

Note

默认情况下仅接受 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

Note

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

Identifier convention

用户和角色变更（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

Note

公共角色无法被删除。

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