API（GraphQL）

使用原生 GraphQL 与 Authing 服务器交互。

Previous开发资源 NextGuard for Web

Last updated 4 years ago

Authing 的 API 未使用 RESTful API，而是使用了 GraphQL。

本文档包含了 Authing 的 GraphQL 请求，可直接复制粘贴使用。

推荐使用：GraphQL 调试器

此调试器允许开发者直接在线上调试 Authing 的 API。

GraphQL 网关

https://users.authing.cn/graphql
https://oauth.authing.cn/graphql

如非特殊说明，以下 GraphQL 都使用 https://users.authing.cn/graphql 网关。

推荐使用 insomnia 调试 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://oauth.authing.cn/graphql

query ReadOAuthList($clientId: String!) {
    ReadOauthList(clientId: $clientId) {
        _id
        name
        image
        description
        enabled
        client
        user
        url
    }
}

注意事项

此接口不需要发送任何 Token

mutation login($unionid: String, $email: String, $phone: String, $password: String, $lastIP: String, $registerInClient: String!, $verifyCode: String, $browser: String, $device: String) {
    login(unionid: $unionid, email: $email, phone: $phone, password: $password, lastIP: $lastIP, registerInClient: $registerInClient, verifyCode: $verifyCode, browser: $browser, device: $device) {
        _id
        email
        emailVerified
        username
        nickname
        company
        phone
        photo
        browser
        token
        tokenExpiredAt
        loginsCount
        lastLogin
        lastIP
        signedUp
        blocked
        isDeleted
    }
}

注意事项

此处（登录）的密码需要加密，Authing 使用了非对称加密算法，加密方式是 PKCS1v1.5。注意，个别语言，如 JavaScript（非 Node ）和 Go 在加密之后还要使用 base64 包一层；
此接口不需要发送任何 Token。

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 接口，接口声明如下：

发送短信验证码

GET https://users.authing.cn/send_smscode/:phone/:clientId

发送验证码给指定手机号

Query Parameters

Name

Type

Description

clientId

string

应用 ID

phone

string

手机号

{"code":200,"message":"发送成功"}

发送注册用短信验证码

GET https://users.authing.cn/notification/send_register_smscode/:phone/:clientId

发送验证码给指定手机号，与直接发送验证码不同的是，它会检测账号是否已经存在。

Query Parameters

Name

Type

Description

clientId

string

应用 ID

phone

string

手机号

通过 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 登录

GET https://users.authing.cn/oauth/oidc/token

Path Parameters

Name

Type

Description

string

password

string

password

client_secret

string

OIDC secret

client_id

string

OIDC ID

Headers

Name

Type

Description

Content-Type

string

application/x-www-form-urlencoded

刷新 OIDC oken

GET https://users.authing.cn/oauth/oidc/token

Path Parameters

Name

Type

Description

refresh_token

string

Your refresh_token

client_secret

string

OIDC secret

client_id

string

OIDC ID

Headers

Name

Type

Description

Content-Type

string

application/x-www-form-urlencoded

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, 
    $phone: String,
    $device: String
) {
    register(userInfo: {
        unionid: $unionid,
        email: $email,
        password: $password,
        lastIP: $lastIP,
        forceLogin: $forceLogin,
        registerInClient: $registerInClient,
        oauth: $oauth,
        registerMethod: $registerMethod,
        photo: $photo,
        phone: $phone,
        username: $username,
        nickname: $nickname,
        device: $device,
        browser: $browser
    }) {
        _id,
        email,
        emailVerified,
        username,
        nickname,
        company,
        photo,
        phone,
        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

读取用户资料

此接口用来读取用户资料，建议使用 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

query decodeJwtToken($token: String){
    decodeJwtToken(token: $token){
        data{
            email
            id
            clientId
            unionid
        }
        status{
            message
            code
            status
        }
        iat
        exp
    }
}

注意事项

此接口不用发送任何 Token。

读取用户绑定的社会化登录

此接口使用的网关为：https://oauth.authing.cn/graphql

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。

推荐使用：GraphQL 调试器

GraphQL 网关

初始化

注意事项

读取用户配置的社会化登录信息

注意事项

登录

注意事项

Public Key

使用手机验证码登录

注意事项

发送短信验证码

发送短信验证码

Query Parameters

发送注册用短信验证码

Query Parameters

通过 AD 登录

通过 LDAP 登录

注意事项

刷新 Token

注意事项

通过 OIDC 登录

Path Parameters

Headers

刷新 OIDC oken

Path Parameters

Headers

Sign In

Refresh SignInToken

注册

注意事项

查询用户是否存在

Public Key

读取用户资料

注意事项

批量查询用户信息

注意事项

读取用户列表

注意事项

检查用户登录状态

注意事项

删除用户数据

注意事项

更新用户资料

注意事项

重置密码流程

注意事项

发送重置密码邮件

验证重置密码验证码

修改密码

发送验证邮件

注意事项

解析 JWT Token

注意事项

读取用户绑定的社会化登录

注意事项

绑定社会化登录

注意事项

取消绑定社会化登录

注意事项

解绑邮箱

注意事项

开启/关闭手机号注册白名单限制

注意事项

查看用户池的手机号白名单开启状态

注意事项

增加手机号到白名单

注意事项

从白名单中删除手机号

注意事项

查看白名单中的手机号

注意事项

查询 MFA 信息

参数

传参说明

注意事项

修改 MFA 信息

参数

传参说明

注意事项