# API(GraphQL)
- API(GraphQL)
- 推荐使用:GraphQL 调试器
- GraphQL 网关
- 初始化
- 读取用户配置的社会化登录信息
- 登录
- 使用手机验证码登录
- 通过 AD 登录
- 通过 LDAP 登录
- 刷新 Token
- Sign In
- Refresh SignInToken
- 注册
- 读取用户资料
- 批量查询用户信息
- 读取用户列表
- 检查用户登录状态
- 删除用户数据
- 更新用户资料
- 重置密码流程
- 发送验证邮件
- 解析 JWT Token
- 读取用户绑定的社会化登录
- 绑定社会化登录
- 取消绑定社会化登录
- 解绑邮箱
- 开启/关闭手机号注册白名单限制
- 查看用户池的手机号白名单开启状态
- 增加手机号到白名单
- 从白名单中删除手机号
- 查看白名单中的手机号
- 查询 MFA 信息
- 修改 MFA 信息
- 查询用户授权过的 SSO 应用列表
- 撤回用户对 SSO 应用的授权
使用原生 GraphQL 与 Authing 服务器交互。
Authing 的 API 未使用 RESTful API,而是使用了 GraphQL。
本文档包含了 Authing 的 GraphQL 请求,可直接复制粘贴使用。
# 推荐使用:GraphQL 调试器
此调试器允许开发者直接在线上调试 Authing 的 API。
# GraphQL 网关
- https://core.authing.cn/graphql
- https://core.authing.cn/graphql
如非特殊说明,以下 GraphQL 都使用 https://core.authing.cn/graphql (opens new window) 网关。
推荐使用 insomnia (opens new window) 调试 GraphQL 请求。
# 初始化
SDK 初始化时获取客户端信息和 accessToken 信息,后续的管理用户的操作请发送此 Token,在下文中,此 Token 命名为「OwnerToken
」。
query getClientWhenSdkInit(
$secret: String
$clientId: String
$retUserId: Boolean
$timestamp: String
$signature: String
$nonce: Int
) {
getClientWhenSdkInit(
secret: $secret
clientId: $clientId
retUserId: $retUserId
timestamp: $timestamp
signature: $signature
nonce: $nonce
) {
accessToken
clientInfo {
_id
name
descriptions
jwtExpired
createdAt
isDeleted
logo
emailVerifiedDefault
registerDisabled
allowedOrigins
clientType {
_id
name
description
image
example
}
}
}
}
# 注意事项
此接口不需要发送任何 Token
# 读取用户配置的社会化登录信息
此接口用来读取用户在 Authing 控制台中配置的 OAuth 信息,enabled 为是否启用。
此接口使用的网关为:https://core.authing.cn/graphql
query ReadOAuthList($clientId: String!) {
ReadOauthList(clientId: $clientId) {
_id
name
image
description
enabled
client
user
url
}
}
# 注意事项
此接口不需要发送任何 Token
# 登录
此接口用来执行用户登录的操作,登录成功后会返回 UserToken
,建议单独维护此 Token。
mutation login(
$unionid: String
$email: String
$password: String
$lastIP: String
$registerInClient: String!
$verifyCode: String
$browser: String
$device: String
) {
login(
unionid: $unionid
email: $email
password: $password
lastIP: $lastIP
registerInClient: $registerInClient
verifyCode: $verifyCode
browser: $browser
device: $device
) {
_id
email
emailVerified
username
nickname
company
photo
browser
token
tokenExpiredAt
loginsCount
lastLogin
lastIP
signedUp
blocked
isDeleted
}
}
# 注意事项
- 此处(登录)的密码需要加密,Authing 使用了非对称加密算法,加密方式是
PKCS1v1.5
。注意,个别语言,如 JavaScript(非 Node )和 Go 在加密之后还要使用base64
包一层; - 此接口不需要发送任何
Token
。
# Public Key
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC4xKeUgQ+Aoz7TLfAfs9+paePb
5KIofVthEopwrXFkp8OCeocaTHt9ICjTT2QeJh6cZaDaArfZ873GPUn00eOIZ7Ae
+TiA2BKHbCvloW3w5Lnqm70iSsUi5Fmu9/2+68GZRH9L7Mlh8cFksCicW2Y2W2uM
GKl64GDcIq3au+aqJQIDAQAB
-----END PUBLIC KEY-----
# 使用手机验证码登录
使用手机验证码的方式登录,登录后返回的 Token 需要在客户端维护。
mutation login(
$phone: String
$phoneCode: Int
$registerInClient: String!
$browser: String
$device: String
) {
login(
phone: $phone
phoneCode: $phoneCode
registerInClient: $registerInClient
browser: $browser
device: $device
) {
_id
email
emailVerified
username
nickname
phone
company
photo
browser
token
tokenExpiredAt
loginsCount
lastLogin
lastIP
signedUp
blocked
isDeleted
}
}
# 注意事项
此接口不用发送任何 Token
。
# 发送短信验证码
发送短信验证码是一个 rest 接口,接口声明如下:
发送短信验证码
发送验证码给指定手机号
发送注册用短信验证码
发送验证码给指定手机号,与直接发送验证码不同的是,它会检测账号是否已经存在。
# 通过 AD 登录
使用 Active Directory 登录,登录后返回的 Token 需要在客户端维护
mutation LoginByAd(
$adConnectorId: String!
$username: String!
$password: String!
) {
LoginByLDAP(
adConnectorId: $adConnectorId
username: $username
password: $password
) {
_id
email
emailVerified
unionid
oauth
registerMethod
username
nickname
company
photo
browser
token
tokenExpiredAt
loginsCount
lastLogin
lastIP
signedUp
blocked
}
}
# 通过 LDAP 登录
使用 LDAP 登录,登录后返回的 Token 需要在客户端维护
mutation LoginByLDAP(
$username: String!
$password: String!
$clientId: String!
$browser: String
$device: String
) {
LoginByLDAP(
username: $username
clientId: $clientId
password: $password
browser: $browser
device: $device
) {
_id
email
emailVerified
unionid
oauth
registerMethod
username
nickname
company
photo
browser
token
tokenExpiredAt
loginsCount
lastLogin
lastIP
signedUp
blocked
}
}
# 注意事项
此接口不用发送任何 Token
。
# 刷新 Token
刷新用户 Token
mutation RefreshToken($client: String!, $user: String!) {
refreshToken(client: $client, user: $user) {
token
iat
exp
}
}
# 注意事项
此接口需发送 OwnerToken
。
通过 OIDC 登录
刷新 OIDC oken
# Sign In
mutation SignIn(
$oidcAppId: String
$email: String
$userPoolId: String
$phone: String
$username: String
$unionid: String
$password: String
) {
signIn(
oidcAppId: $oidcAppId
userPoolId: $userPoolId
email: $email
phone: $phone
password: $password
username: $username
unionid: $unionid
) {
sub
birthdate
family_name
gender
given_name
locale
middle_name
name
nickname
picture
preferred_username
profile
updated_at
website
zoneinfo
username
_id
company
browser
device
logins_count
register_method
blocked
last_ip
register_in_userpool
last_login
signed_up
email
email_verified
phone_number
phone_number_verified
token
access_token
id_token
refresh_token
expires_in
token_type
scope
}
}
# Refresh SignInToken
mutation RefreshSignInToken(
$oidcAppId: String
$userPoolId: String
$refreshToken: String!
) {
refreshSignInToken(
oidcAppId: $oidcAppId
userPoolId: $userPoolId
refreshToken: $refreshToken
) {
id_token
access_token
refresh_token
scope
expires_in
}
}
# 注册
mutation register(
$unionid: String
$email: String
$password: String
$lastIP: String
$forceLogin: Boolean
$registerInClient: String!
$oauth: String
$username: String
$nickname: String
$registerMethod: String
$photo: String
$browser: String
$device: String
) {
register(
userInfo: {
unionid: $unionid
email: $email
password: $password
lastIP: $lastIP
forceLogin: $forceLogin
registerInClient: $registerInClient
oauth: $oauth
registerMethod: $registerMethod
photo: $photo
username: $username
nickname: $nickname
device: $device
browser: $browser
}
) {
_id
email
emailVerified
username
nickname
company
photo
browser
password
token
group {
name
}
blocked
device
}
}
# 注意事项
- 此处(登录)的密码需要加密,Authing 使用了非对称加密算法,加密方式是
PKCS1v1.5
。注意,个别语言,如 JavaScript(非 Node)和 Go 在加密之后还要使用base64
包一层。 - 此接口不需要发送任何
Token
。
# 查询用户是否存在
此接口可以查询符合条件的用户是否存在,避免重复注册。
query userExist(
$userPoolId: String!
$phone: String
$username: String
$email: String
) {
userExist(
userPoolId: $userPoolId
phone: $phone
username: $username
email: $email
)
}
# Public Key
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC4xKeUgQ+Aoz7TLfAfs9+paePb
5KIofVthEopwrXFkp8OCeocaTHt9ICjTT2QeJh6cZaDaArfZ873GPUn00eOIZ7Ae
+TiA2BKHbCvloW3w5Lnqm70iSsUi5Fmu9/2+68GZRH9L7Mlh8cFksCicW2Y2W2uM
GKl64GDcIq3au+aqJQIDAQAB
-----END PUBLIC KEY-----
# 读取用户资料
此接口用来读取用户资料,建议使用 OwnerToken
query user($id: String!, $registerInClient: String!) {
user(id: $id, registerInClient: $registerInClient) {
_id
email
emailVerified
username
nickname
company
photo
browser
registerInClient
registerMethod
oauth
token
tokenExpiredAt
loginsCount
lastLogin
lastIP
signedUp
blocked
isDeleted
userLocation {
_id
when
where
}
userLoginHistory {
totalCount
list {
_id
when
success
ip
result
}
}
}
}
# 注意事项
此接口需要发送 Token,建议直接使用 OwnerToken
。
# 批量查询用户信息
批量查询用户,ids 是一个字符串,用逗号分隔 id。
query userPatch($ids: String) {
userPatch(ids: $ids) {
list {
_id
unionid
email
emailVerified
username
nickname
company
photo
browser
registerInClient
registerMethod
oauth
token
tokenExpiredAt
loginsCount
lastLogin
lastIP
signedUp
blocked
isDeleted
userLocation {
_id
when
where
}
userLoginHistory {
totalCount
list {
_id
when
success
ip
result
}
}
}
totalCount
}
}
# 注意事项
此接口需要OwnerToken
。
# 读取用户列表
此接口用来读取用户列表,建议使用 OwnerToken
query users($registerInClient: String, $page: Int, $count: Int) {
users(registerInClient: $registerInClient, page: $page, count: $count) {
totalCount
list {
_id
email
emailVerified
username
nickname
company
photo
browser
password
registerInClient
token
tokenExpiredAt
loginsCount
lastLogin
lastIP
signedUp
blocked
isDeleted
group {
_id
name
descriptions
createdAt
}
clientType {
_id
name
description
image
example
}
userLocation {
_id
when
where
}
userLoginHistory {
totalCount
list {
_id
when
success
ip
result
}
}
systemApplicationType {
_id
name
descriptions
price
}
}
}
}
# 注意事项
此接口需要发送 Token,建议直接使用 OwnerToken
。
# 检查用户登录状态
此接口检查用户登录状态,请使用 UserToken
query checkLoginStatus {
checkLoginStatus {
status
code
message
}
}
# 注意事项
此接口需要发送 Token,请使用 UserToken
。
# 删除用户数据
此接口用来删除用户数据,建议使用 OwnerToken
mutation removeUsers($ids: [String], $registerInClient: String, $operator: String){
removeUsers(ids: $ids, registerInClient: $registerInClient, operator: $operator) {
_id
}
}
# 注意事项
此接口需要发送 Token,建议直接使用 OwnerToken
。
# 更新用户资料
此接口用来更新用户资料,建议使用 OwnerToken
mutation UpdateUser(
$_id: String!
$email: String
$emailVerified: Boolean
$username: String
$nickname: String
$company: String
$photo: String
$browser: String
$password: String
$oldPassword: String
$registerInClient: String!
$token: String
$tokenExpiredAt: String
$loginsCount: Int
$lastLogin: String
$lastIP: String
$signedUp: String
$blocked: Boolean
$isDeleted: Boolean
) {
updateUser(
options: {
_id: $_id
email: $email
emailVerified: $emailVerified
username: $username
nickname: $nickname
company: $company
photo: $photo
browser: $browser
password: $password
oldPassword: $oldPassword
registerInClient: $registerInClient
token: $token
tokenExpiredAt: $tokenExpiredAt
loginsCount: $loginsCount
lastLogin: $lastLogin
lastIP: $lastIP
signedUp: $signedUp
blocked: $blocked
isDeleted: $isDeleted
}
) {
_id
email
emailVerified
username
nickname
company
photo
browser
registerInClient
registerMethod
oauth
token
tokenExpiredAt
loginsCount
lastLogin
lastIP
signedUp
blocked
isDeleted
}
}
# 注意事项
此接口需要发送 Token,建议直接使用 OwnerToken
。
# 重置密码流程
- sendResetPasswordEmail 发送重置密码邮件给用户
- verifyResetPasswordVerifyCode 检查验证码是否正确
- changePassword 使用新的密码和验证码来修改密码
# 注意事项
以下三个修改密码的 Token 可以不发送任何Token
。
# 发送重置密码邮件
mutation sendResetPasswordEmail($email: String!, $client: String!) {
sendResetPasswordEmail(email: $email, client: $client) {
message
code
status
}
}
# 验证重置密码验证码
mutation verifyResetPasswordVerifyCode(
$email: String!
$client: String!
$verifyCode: String!
) {
verifyResetPasswordVerifyCode(
email: $email
client: $client
verifyCode: $verifyCode
) {
message
code
status
}
}
# 修改密码
此接口用来更改忘记密码后的新密码,需要携带 verifyCode,不用发送 Token
,正常的密码修正请使用上面的 update
接口。
mutation changePassword(
$email: String!
$client: String!
$password: String!
$verifyCode: String!
) {
changePassword(
email: $email
client: $client
password: $password
verifyCode: $verifyCode
) {
_id
email
emailVerified
username
nickname
company
photo
browser
registerInClient
registerMethod
oauth
token
tokenExpiredAt
loginsCount
lastLogin
lastIP
signedUp
blocked
isDeleted
}
}
# 发送验证邮件
mutation sendVerifyEmail($email: String!, $client: String!) {
sendVerifyEmail(email: $email, client: $client) {
message
code
status
}
}
# 注意事项
此接口不用发送任何 Token
。
# 解析 JWT Token
解析 JWT Token
query decodeJwtToken($token: String) {
decodeJwtToken(token: $token) {
data {
email
id
clientId
unionid
}
status {
message
code
status
}
iat
exp
}
}
# 注意事项
此接口不用发送任何 Token
。
# 读取用户绑定的社会化登录
读取用户绑定的社会化登录
query notBindOAuthList($user: String, $client: String) {
notBindOAuthList(user: $user, client: $client) {
type
oAuthUrl
image
name
binded
}
}
# 注意事项
此接口发送 OwnerToken
。
# 绑定社会化登录
用户绑定第三方登录方式
mutation bindOtherOAuth(
$user: String
$client: String
$type: String!
$unionid: String!
$userInfo: String!
) {
bindOtherOAuth(
user: $user
client: $client
type: $type
unionid: $unionid
userInfo: $userInfo
) {
_id
user
client
type
unionid
userInfo
createdAt
}
}
# 注意事项
此接口发送 UserToken
。
# 取消绑定社会化登录
用户解绑第三方登录方式
mutation unbindOtherOAuth($user: String, $client: String, $type: String!) {
unbindOtherOAuth(user: $user, client: $client, type: $type) {
_id
user
client
type
unionid
userInfo
createdAt
}
}
# 注意事项
此接口发送 UserToken
。
# 解绑邮箱
用户解绑 Email
mutation unbindEmail($user: String, $client: String) {
unbindEmail(user: $user, client: $client) {
_id
email
emailVerified
username
nickname
company
photo
browser
registerInClient
registerMethod
oauth
token
tokenExpiredAt
loginsCount
lastLogin
lastIP
signedUp
blocked
isDeleted
}
}
# 注意事项
此接口发送 UserToken
。
# 开启/关闭手机号注册白名单限制
开启或关闭手机号注册时的白名单限制
mutation setInvitationState($client: String!, $enableQrCode: Boolean) {
setInvitationState(client: $client, enableQrCode: $enableQrCode) {
client
enableQrCode
createdAt
updatedAt
}
}
# 注意事项
此接口需要发送 Token,建议直接使用 OwnerToken
。
# 查看用户池的手机号白名单开启状态
query queryInvitationState($client: String!) {
queryInvitationState(client: $client) {
client
enableQrCode
}
}
# 注意事项
此接口需要发送 Token,建议直接使用 OwnerToken
。
# 增加手机号到白名单
mutation addToInvitation($client: String!, $qrCodPhone: String) {
addToInvitation(client: $client, qrCodePhone: $qrCodPhone) {
client
qrCodePhone
}
}
# 注意事项
此接口需要发送 Token,建议直接使用 OwnerToken
。
# 从白名单中删除手机号
mutation removeFromInvitation($client: String!, $qrCodePhone: String) {
removeFromInvitation(client: $client, qrCodePhone: $qrCodePhone) {
client
qrCodePhone
}
}
# 注意事项
此接口需要发送 Token,建议直接使用 OwnerToken
。
# 查看白名单中的手机号
query queryInvitation($client: String!) {
queryInvitation(client: $client) {
client
qrCodePhone
}
}
# 注意事项
此接口需要发送 Token,建议直接使用 OwnerToken
。
# 查询 MFA 信息
query queryMFA(
$_id: String
$userId: String
$userPoolId: String
$page: Int
$count: Int
) {
queryMFA(
_id: $_id
userId: $userId
userPoolId: $userPoolId
page: $page
count: $count
) {
_id
userId
userPoolId
enable
shareKey
}
}
# 参数
- _id
{String},MFA 主体的 id
- userPoolId
{String},用户池 id
- userId
{String},用户 id
- page
{Int},分页页码
- count
{Int},每页数目
# 传参说明
- 通过用户 id 和用户池 id 参数来查询一个用户的 MFA 信息,此时 userId 和 userPoolId 两个参数必填。
- 也可以通过 MFA 主体的 id 来查询 MFA 的信息,此时只需传入 _id 参数,userId 和 userPoolId 参数可以不传。
# 注意事项
此接口需要发送 Token,可以使用 OwnerToken
或 UserToken
。
# 修改 MFA 信息
mutation changeMFA(
$_id: String
$userId: String
$userPoolId: String
$enable: Boolean!
$refreshKey: Boolean
) {
changeMFA(
_id: $_id
userId: $userId
userPoolId: $userPoolId
enable: $enable
refreshKey: $refreshKey
) {
_id
userId
userPoolId
shareKey
enable
}
}
# 参数
- _id
{String},MFA 主体的 id
- userPoolId
{String},用户池 id
- userId
{String},用户 id
- enable
{Boolean},打开或关闭 MFA
- refreshKey
{Boolean},是否刷新 MFA secret
# 传参说明
- 通过用户 id 和用户池 id 参数来指定一个用户的 MFA 状态,此时 userId 和 userPoolId 两个参数必填。
- 也可以通过 MFA 主体的 id 来修改 MFA 的状态,此时只需传入 _id 参数,userId 和 userPoolId 参数可以不传。
# 注意事项
此接口需要发送 Token,必须使用 UserToken
。
# 查询用户授权过的 SSO 应用列表
此接口用于查询一个用户池内,用户授权过的 SSO 应用列表。
query GetUserAuthorizedApps(
$clientId: String
$userId: String
$page: Int
$count: Int
) {
GetUserAuthorizedApps(
clientId: $clientId
userId: $userId
page: $page
count: $count
) {
OAuthApps {
_id
name
domain
clientId
description
isDeleted
grants
redirectUris
when
}
OIDCApps {
_id
name
client_id
domain
description
authorization_code_expire
when
isDeleted
id_token_signed_response_alg
response_types
grant_types
token_endpoint_auth_method
redirect_uris
image
access_token_expire
id_token_expire
cas_expire
}
totalCount
}
}
# 参数
- clientId
{String},必须,用户池 id
- userId
{String},必须,用户 id
- page
{Number},可选,页数,默认 1
- count
{Number},可选,每页数目,默认 10
返回示例
{
"OAuthApps": [
{
"_id": "5d5a8a7bbc7275af2cb71920",
"name": "test1",
"domain": "test123",
"clientId": "5d5921ffaa016518f658498d",
"description": "",
"isDeleted": false,
"grants": [
"authorization_code",
"implicit",
"refresh_token"
],
"redirectUris": [
"http://qq.com"
],
"when": "Mon Aug 19 2019 19:39:39 GMT+0800 (CST)"
},
{
"_id": "5d5e2e8b026f9d145bf89203",
"name": "oauth1",
"domain": "oauth1",
"clientId": "5d5921ffaa016518f658498d",
"description": "",
"isDeleted": false,
"grants": [
"authorization_code",
"implicit",
"refresh_token"
],
"redirectUris": [
"http://qq.com"
],
"when": "Thu Aug 22 2019 13:56:27 GMT+0800 (CST)"
}
],
"OIDCApps": [
{
"_id": "5d5a85e258375a32d1133d45",
"name": "test1",
"client_id": "5d5a85e258375a32d1133d45",
"domain": "test1",
"description": "test1",
"authorization_code_expire": "600",
"when": "Mon Aug 19 2019 19:20:02 GMT+0800 (CST)",
"isDeleted": false,
"id_token_signed_response_alg": "HS256",
"response_types": [
"code"
],
"grant_types": [
"authorization_code",
"refresh_token"
],
"token_endpoint_auth_method": "client_secret_post",
"redirect_uris": [
"http://qq.com"
],
"image": "https://usercontents.authing.cn/client/logo@2.png",
"access_token_expire": "3600",
"id_token_expire": "3600",
"cas_expire": "3600"
}
],
"totalCount": 3
}
# 注意事项
此接口需要发送 Token,可以使用 UserToken
或 OwnerToken
。
# 撤回用户对 SSO 应用的授权
此接口用于撤回一个用户池内,某个用户对该用户池下的某个 SSO 应用的授权。撤回授权后,用户在 SSO 登录页面登录时,会再次显示确权页面。
mutation RevokeUserAuthorizedApp(
$userPoolId: String
$userId: String
$appId: String
) {
RevokeUserAuthorizedApp(
userPoolId: $userPoolId
userId: $userId
appId: $appId
) {
isRevoked
_id
scope
}
}
# 参数
- userPoolId
{String},必须,用户池 id
- userId
{String},必须,用户 id
- appId
{String},必须,SSO 应用 id
返回示例
{
"isRevoked": "true",
"_id": "5d7661e17a9f981da5fa8098",
"scope": "profile"
}
# 注意事项
此接口需要发送 Token,可以使用 UserToken
或 OwnerToken
。