API 查询与变更¶
Authany 提供了一个 GraphQL API，您可以直接在应用中使用它来管理用户和其他资源，也可以通过 Authany 管理台 > 高级 > Admin API 中的 GraphiQL Explorer 来使用。
以下部分详细介绍了支持的查询和变更，并提供了相应示例。
1. 查询¶
1.1. auditLogs¶
auditLogs 查询会返回审计日志中所有活动（日志）的列表。
Schema：
auditLogs(
first: Int
last: Int
userIDs: [ID!]
sortDirection: SortDirection
before: String
after: String
rangeFrom: DateTime
rangeTo: DateTime
activityTypes: [AuditLogActivityType!]
): AuditLogConnection
示例：
1.2. users¶
您可以使用此查询获取应用中所有已注册的用户。users 查询会返回一个 User 类型的列表。
users 查询依赖于搜索索引，因此它返回的数据不是实时一致的——需要重新建立索引后，最新的数据和更新才会被包含进去。如果您的场景需要获取实时的用户数据，请考虑改用 node/nodes 或 getUser/getUsers 查询。
Schema：
users(
first: Int
last: Int
searchKeyword: String
sortBy: UserSortBy
sortDirection: SortDirection
before: String
after: String
): UserConnection
示例：
{
"data": {
"users": {
"edges": [
{
"node": {
"id": "VXNlcjo4ZGM4ZDgyjjkoKA0LTRjZGEtODZiOC03OTY4MGUwYzA5OGM",
"standardAttributes": {
"email": "myuser@gmail.com",
"email_verified": true,
"family_name": "John",
"given_name": "Doe",
"updated_at": 1686820949
}
}
},
{
"node": {
"id": "VXNlcjplMzA3OTAyaxKJuILTRjMjQtOTFjMS1jMmNkNjNhNmE0YWY",
"standardAttributes": {
"email": "user2@gmail.com",
"email_verified": true,
"family_name": "Eliano",
"given_name": "Don",
"updated_at": 1694359032
}
}
}
]
}
}
}
1.3. node¶
node（节点）代表不同类型中的单个对象。node 查询允许您使用节点 ID 查询单个对象。您可以在这里了解更多关于节点 ID 的信息。
Schema：
示例：
您可以为 node 查询指定不同的对象类型，以获取该类型的一个条目。节点类型（node Types）的例子包括 User、AuditLog、Session、Authenticator、Authorization 和 Identity。
下面的示例使用了 AuditLog 节点类型。
1.4. nodes¶
nodes 查询会返回一个节点列表。它的用法与 node 查询类似，区别在于您提供的不是单个 ID，而是要查询对象的 ID 列表。
Schema：
示例：
1.5 groups¶
groups 查询会返回 Authany 项目中所有用户组的列表。如果还没有创建任何用户组，则不会返回任何内容。用户组也可以作为 roles 查询中的一个字段。
Schema：
groups(
searchKeyword: String
excludedIDs: [ID!]
after: String
first: Int
last: Int
before: String
): GroupConnection
示例：
{
"data": {
"groups": {
"edges": [
{
"cursor": "b2Zmc2V0OjA",
"node": {
"description": "Staff members with super admin permissions",
"id": "R3JvdXA6OTU4YTA2ODIXRMb4n6MDAwMDAwMDAwMDA0ZDVjUKx",
"key": "admin_staff"
}
},
{
"cursor": "b2Zmc2V0OjE",
"node": {
"description": "Group for quickly applying team_member role to batch users.",
"id": "R3JvdXA6XRMb4n6MDAwMDAwMDAwMDA0ZDVjUKJl",
"key": "regular_staff"
}
}
]
}
}
}
1.6 roles¶
您可以使用此查询获取 Authany 项目中所有可用的角色。如果该项目还没有创建任何角色，roles 查询将不会返回任何内容。角色也可以作为 groups 查询节点中的一个字段。参见管理用户角色和用户组以了解更多关于角色和用户组的信息。
Schema：
roles(
excludedIDs: [ID!]
last: Int
before: String
after: String
first: Int
searchKeyword: String
): RoleConnection
示例：
{
"data": {
"roles": {
"edges": [
{
"cursor": "b2Zmc2V0OjA",
"node": {
"description": "Leads a specific department where they also work.",
"groups": {
"edges": []
},
"id": "Um9sZTozMjc5NWRiNhOTgtOTzMzZkZGNi1hOWVkLTE2MC0RlOWFkMTM",
"key": "department_lead"
}
},
{
"cursor": "b2Zmc2V0OjE",
"node": {
"description": "Regular staff working in a specific department.",
"groups": {
"edges": [
{
"node": {
"key": "regular_staff"
}
}
]
},
"id": "Um9sZToyMjc5NWRiNhOTgtOTzMzZkZGNi1hOWVkLTE2MC0RlOWFkZTA",
"key": "team_member"
}
}
]
}
}
}
1.7 getUser 和 getUsers 查询¶
getUser 和 getUsers 查询是一组 Admin API 查询，用于以特定属性作为搜索键，实时获取单个或多个用户的详细信息。与 users() 查询不同，getUser 和 getUsers 查询返回的结果是实时一致的。
您可以在这里了解这组查询中所有查询的更多信息。
1.8 User.accountLockout¶
User 类型上的 accountLockout 字段会返回某个用户当前的账号锁定状态。您可以在任何返回 User 的查询中选取该字段（例如 1.3 节中的 node 查询，或 1.7 节中的 getUser/getUsers 查询）。
Schema：
type AccountLockout {
lockoutType: LockoutType!
isLocked: Boolean!
lockedUntil: DateTime
lockedIPs: [LockedIP!]!
}
type LockedIP {
ipAddress: String!
lockedUntil: DateTime!
}
enum LockoutType {
per_user
per_user_per_ip
}
响应的结构取决于项目所配置的锁定类型（Lockout Type）：
- 对于
per_user，lockedUntil是锁定到期的时间（UTC），lockedIPs为空。 - 对于
per_user_per_ip，lockedUntil为null，lockedIPs会列出每个当前被锁定的 IP 及各自的到期时间，按到期时间降序排列。
示例：
{
"data": {
"node": {
"id": "VXNlcjowNGUyJJO4Mi04NmEzLTRjYjItOGQxNy14ZWU0Y2FlNzQ5Kse",
"accountLockout": {
"lockoutType": "per_user_per_ip",
"isLocked": true,
"lockedUntil": null,
"lockedIPs": [
{ "ipAddress": "192.0.2.10", "lockedUntil": "2026-05-15T14:53:50Z" },
{ "ipAddress": "192.0.2.42", "lockedUntil": "2026-05-15T14:31:18Z" }
]
}
}
}
}
参见账号锁定，了解该功能概览以及如何解锁用户。
2. 变更¶
通过变更（mutation），您可以使用 Admin API GraphQL 在应用中修改数据。例如，您可以使用变更来更新
2.1. anonymizeUser¶
调用此变更会将指定的用户账号转换为匿名账号。换句话说，该操作会匿名化指定用户，并删除该用户的姓名、性别等数据。
Schema：
示例：
2.2. createIdentity¶
createIdentity 变更会为用户创建一个新的身份（identity）。
Schema：
说明
注意：要使用任意 loginID key，您必须先在 Authany 管理台中启用对应的登录方式。例如，要使用手机号码创建身份，需要先启用 Mobile 登录方式。
示例：
{
"data": {
"createIdentity": {
"identity": {
"claims": {
"email": "user@gmail.com",
"https://authgear.com/claims/login_id/key": "email",
"https://authgear.com/claims/login_id/original_value": "user@gmail.com",
"https://authgear.com/claims/login_id/type": "email",
"https://authgear.com/claims/login_id/value": "user@gmail.com"
},
"id": "SWRlbnRpdHk6YjHiZGVhNjctABCwMy00OWU2LWIyOTMtNTIwMGU3KKUkMTBl"
}
}
}
}
2.3. createUser¶
createUser 变更让您可以通过 Admin API 创建新的用户账号。
Schema：
示例：
mutation {
createUser(input: {definition: {loginID: {key: "email", value: "user@gmail.com"}}, password:"my$ecurepa55", sendPassword: true, setPasswordExpired: true}) {
user{
id
standardAttributes
}
}
}
关于 password 的说明：
- 如果
password是空字符串（""），仅当项目已启用password时，服务器才会生成一个密码。 - 您可以在输入中包含
sendPassword: true和setPasswordExpired: true，将新密码发送给用户，并将其设为已过期状态，以便用户在下次登录时设置新密码。 - 如果
password为 null，则无论项目如何配置，都不会创建密码。
2.4. deleteAuthenticator¶
此变更会删除指定用户的一个身份验证器（authenticator）。
Schema：
示例：
2.5. deleteAuthorization¶
您可以使用 deleteAuthorization 变更删除用户现有的一个授权（authorization）。
Schema：
示例：
2.6. deleteIdentity¶
deleteIdentity 变更会删除用户的某个身份（identity）。
Schema：
示例：
2.7. deleteUser¶
此变更允许您通过 Admin API 删除指定用户。
Schema：
示例：
2.8. generateOOBOTPCode¶
调用 generateOOBOTPCode 变更会为用户生成一个新的 OOB OTP 验证码。此变更允许您在输入中指定 OTP 的用途（purpose）和目标（target）。
Schema：
示例：
2.9. resetPassword¶
resetPassword 变更让您可以通过 Admin API 重置用户的密码。此功能仅适用于已经拥有密码的用户，不能用于通过第三方服务（如 Google）注册的用户。
Schema：
示例 1：
示例 2（向用户发送新密码）：
您可以在 resetPassword 变更中包含以下内容：
sendPassword: true将新密码发送给用户setPasswordExpired: true强制用户在下次登录时修改密码。
mutation {
resetPassword(input: {userID: "<ENCODED USER ID>", password: "n3w-p4$s", sendPassword: true, setPasswordExpired: true}) {
user {
id
standardAttributes
}
}
}
2.10. revokeAllSessions¶
通过 revokeAllSessions 变更，您可以撤销指定用户的所有会话。
Schema：
示例：
2.11. revokeSession¶
此变更会撤销指定的用户会话。您可以通过会话 ID 指定要撤销的会话。
Schema：
示例：
2.12. scheduleAccountAnonymization¶
scheduleAccountAnonymization 变更提供了一种通过 Admin API 安排用户账号匿名化的方式。
Schema：
scheduleAccountAnonymization(input: ScheduleAccountAnonymizationInput!): ScheduleAccountAnonymizationPayload!
示例：
2.13. scheduleAccountDeletion¶
scheduleAccountDeletion 变更提供了一种通过 Admin API 安排用户账号删除的方式。
Schema：
scheduleAccountDeletion(input: ScheduleAccountDeletionInput!): ScheduleAccountDeletionPayload!
示例：
2.14. sendResetPasswordMessage¶
您可以使用 sendResetPasswordMessage 变更，通过 Admin API 向用户发送密码重置消息。
Schema：
示例：
2.15. setDisabledStatus¶
setDisabledStatus 变更让您可以启用或禁用用户账号。
Schema：
示例：
2.16. setVerifiedStatus¶
您可以使用 setVerifiedStatus 变更，通过 Admin API 将用户设置为已验证或未验证状态。
Schema：
示例：
2.17. unscheduleAccountAnonymization¶
此变更允许您取消此前已安排的变更操作。
Schema：
unscheduleAccountAnonymization(input: UnscheduleAccountAnonymizationInput!): UnscheduleAccountAnonymizationPayload!
示例：
2.18. unscheduleAccountDeletion¶
此变更允许您取消此前已安排的删除操作。
Schema：
unscheduleAccountDeletion(input: UnscheduleAccountDeletionInput!): UnscheduleAccountDeletionPayload!
示例：
2.19. updateIdentity¶
updateIdentity 变更用于更新用户现有的一个身份（identity）。
Schema：
示例：
2.20. updateUser¶
您可以使用此变更更新现有用户的详细信息，包括 email、phone、family_name、given_name 和 gender 等标准属性；也可以通过 customAttributes 参数修改自定义字段。
说明
注意： 要使用此变更更新用户的 email、phone 或 username 标准属性，您必须先将新值添加到该用户的 Identities 中。参见 createIdentity 变更和 updateIdentity。
Schema：
示例 1（标准属性）：
在这个 updateUser 示例中，我们将更新一个用户的标准属性。首先需要将该用户所有标准属性的当前值提取到一个变量中，然后在变量中添加新字段，或用新值修改已有字段。
注意： 对于您不想更新但仍希望保留的字段，务必在变量中包含其当前值。如果变量中省略了某个已有字段，Admin API 会将其删除。
下面的代码块展示了一个变量示例。如果您使用的是 GraphiQL，只需在 GraphiQL 的变量（variable）标签页中按如下方式创建该变量：
示例 2（自定义属性）
下面的示例展示了如何更新自定义属性。
注意： 您必须先在 Authany 管理台 > 用户资料 > 自定义属性 中创建好您想要更新的自定义属性。
创建一个变量，并将当前的自定义属性提取到其中，然后修改您想更新的属性值，或添加新的属性。
注意： 同样地，对于您不想更新但仍希望保留的字段，务必包含其当前值。如果变量中省略了某个已有字段，Admin API 会将其删除。
下面的代码块展示了该变量的示例。您可以在 GraphiQL 的变量标签页中设置该变量。
2.21 createGroup¶
运行此变更，为您的 Authany 应用添加一个新的访问管理用户组。
Schema：
示例：
注意： key 的值不能为空，长度必须在 1 到 40 个字符之间，允许使用的字符为 [a-zA-Z0-9:_]，前缀 authgear: 保留供 Authany 内部使用。
2.22 createRole¶
您可以使用此变更为您的 Authany 应用添加一个新的访问管理角色。
Schema：
示例：
注意： key 的值不能为空，长度必须在 1 到 40 个字符之间，允许使用的字符为 [a-zA-Z0-9:_]，前缀 authgear: 保留供 Authany 内部使用。
2.23 addRoleToGroups¶
使用此变更，可以在一次操作中将一个角色添加到一个或多个用户组。
Schema：
示例：
2.24 addGroupToRoles¶
在一次操作中，将一个用户组添加到一个或多个角色。
Schema：
示例：
2.25 addUserToRoles¶
在一次操作中，将一个用户添加到一个或多个角色。
Schema：
示例：
2.26 addRoleToUsers¶
在一次操作中，将一个角色添加到一个或多个用户。
Schema：
示例：
2.27 addUserToGroups¶
在一次操作中，将一个用户添加到一个或多个用户组。
Schema：
示例：
2.28 addGroupToUsers¶
在一次操作中，将一个用户组添加到一个或多个用户。
Schema：
示例：
2.29 updateRole¶
更新现有角色的详细信息。
Schema：
示例：
注意： 如果不想更新 key、name 或 description，请将其值传为 null；如果想删除 name 和 description 的值，请传入空字符串（""）。另外，有些 GraphQL 库可能不允许在查询中直接传入字面量 null，遇到这种情况，请使用变量来定义 input 的值。
2.30 updateGroup¶
更新现有用户组的详细信息。
Schema：
示例：
注意： 如果不想更新 key、name 或 description，请将其值传为 null；如果想删除 name 和 description 的值，请传入空字符串（""）。另外，有些 GraphQL 库可能不允许在查询中直接传入字面量 null，遇到这种情况，请使用变量来定义 input 的值。
2.31 removeUserFromGroups¶
将一个用户从其当前所在的一个或多个用户组中移除。
Schema：
示例：
2.32 removeRoleFromGroups¶
将一个角色从一个或多个用户组中移除。
Schema：
示例：
2.33 removeUserFromRoles¶
将一个用户从一个或多个角色中移除。
Schema：
示例：
2.34 removeGroupFromRoles¶
在一次操作中，将一个用户组从一个或多个角色中移除。
Schema：
示例：
2.35 removeRoleFromUsers¶
在一次操作中，将一个角色从一个或多个用户中移除。
Schema：
示例：
2.36 removeGroupFromUsers¶
在一次操作中，将一个用户组从一个或多个用户中移除。
Schema：
示例：
2.37 deleteGroup¶
使用此变更删除一个现有的用户组。
Schema：
示例：
2.38 deleteRole¶
使用此变更删除一个现有的角色。
Schema：
示例：
2.39 resetAccountLockout¶
resetAccountLockout 变更会清除某个用户的所有账号锁定状态，使其无需等待锁定时长结束即可立即重新进行身份验证。该变更会清除所有参与账号锁定的身份验证器类型（密码、TOTP、OOB OTP、恢复代码）的锁定状态。对于 per_user 锁定，会清除全局锁定；对于 per_user_per_ip 锁定，会清除该用户所有基于 IP 的锁定。如果账号锁定功能未配置或未启用，该变更会成功执行但不产生任何效果。
Schema：
示例：
参见账号锁定，了解该功能概览，包括如何在 Authany 管理台中解锁用户。