¶ 核心认证 API

更新时间: 2023-07-28 14:42:17

¶ 邮箱注册

使用邮箱注册帐号，邮箱不区分大小写且用户池内唯一。此接口不要求用户对邮箱进行验证，用户注册之后 emailVerified 字段会为 false 。

static Future<AuthResult> registerByEmail(String email, String password) async

参数

email 邮箱
password 明文密码

示例

AuthResult result = await AuthClient.registerByEmail("test@example.com", "strong");
User user = result.user;

错误码

2003 非法邮箱地址
2026 邮箱已注册

¶ 用户名注册

通过用户名注册帐号。用户名区分大小写且用户池内唯一。

static Future<AuthResult> registerByUserName(String username, String password) async

参数

username 用户名
password 明文密码

示例

AuthResult result = await AuthClient.registerByUserName("test", "strong");
User user = result.user;

错误码

2026 用户名已存在

¶ 短信验证码注册

通过手机号和短信验证码注册帐号。手机号需要在用户池内唯一。调用此接口之前，需要先调用发送短信验证码接口以获取短信验证码。

static Future<AuthResult> registerByPhoneCode(String phone, String code, String password, {String? phoneCountryCode}) async

参数

phone 手机号
code 短信验证码
password 明文密码
phoneCountryCode 国家码

示例

AuthResult result = await AuthClient.registerByPhoneCode("188xxxx8888", "code", "strong", phoneCountryCode: "+86");
User user = result.user;

错误码

2001 验证码错误
2026 手机号已注册

¶ 帐号密码登录

static Future<AuthResult> loginByAccount(String account, String password) async

参数

account 可以是手机号 / 邮箱 / 用户名
password 明文密码

示例

AuthResult result = await AuthClient.loginByAccount("test", "your password");
User user = result.user; // user info

错误码

2333 帐号或密码错误

¶ 手机验证码登录

通过短信验证码登录，需要先调用发送短信验证码接口。

static Future<AuthResult> loginByPhoneCode(String phone, String code, {String? phoneCountryCode}) async

参数

phone 手机号
code 短信验证码
phoneCountryCode 国家码

示例

AuthResult result = await AuthClient.loginByPhoneCode("188xxxx8888", "code", phoneCountryCode: "+86");
User user = result.user; // get user info

错误码

2001 短信验证码不正确

¶ 获取当前登录的用户信息

获取当前登录的用户信息，需要先登录。

static Future<AuthResult> getCurrentUser() async

示例

AuthResult result = await AuthClient.getCurrentUser();
User user = result.user; // user info

错误码

2020 未登录

¶ 退出登录

退出登录，同时清除内存以及本地持久化的 token 和用户信息。

static Future<AuthResult> logout() async

示例

AuthResult result = await AuthClient.logout();
var code = result.code;

错误码

1010001 如果用户的 id token 非法或者过期

¶ 发送短信验证码

向指定的手机发送短信验证码。

static Future<AuthResult> sendSms(String phone, [String? phoneCountryCode]) async

参数

phone 手机号
phoneCountryCode 电话国家码。可以为空，为空时默认为 +86

示例

AuthResult result = await AuthClient.sendSms("188xxxx8888", "+86");
var code = result.code;

错误码

500 手机号码格式非法

¶ 发送邮件

给指定邮箱发送邮件。

static Future<AuthResult> sendEmail(String email, String scene) async

参数

email 邮箱地址
scene 发送场景，可选值包含：
- RESET_PASSWORD: 发送重置密码邮件，邮件中包含验证码
- CHANGE_EMAIL: 发送修改邮箱邮件，邮件中包含验证码
- MFA_VERIFY: 发送 MFA 验证邮件
- VERIFY_CODE: 发送验证码

示例

AuthResult result = await AuthClient.sendEmail("test@example.com", "RESET_PASSWORD");
var code = result.code;

错误码

1020017 邮箱地址非法

¶ 获取用户自定义数据

获取用户自定义数据，你需要先在用户池定义用户自定义数据元信息，

用户自定义数据会添加到传入的 userInfo 对象里面，

调用此接口需要先登录。

static Future<AuthResult> getCustomData(String userId) async

参数

userInfo 用户信息对象

示例

AuthResult result = await AuthClient.getCustomData("user_id");
var value = AuthClient.currentUser?.customData[0]["key"], "your_custom_field_key");

错误码

2020 未登录

¶ 设置用户自定义数据

设置用户的自定义数据。你需要先在用户池定义用户自定义数据元信息，且传入值的类型必须和定义的类型匹配，调用此接口需要先登录。

static Future<AuthResult> setCustomData(List data) async

参数

customData key-value 形式的 JSONObject 对象

示例

AuthClient.currentUser?.customData[0]["value"] = "hello";
AuthResult result = await AuthClient.setCustomData(AuthClient.currentUser!.customData);

错误码

2020 未登录

¶ 通过短信验证码重置密码

通过短信验证码重置密码，你可以通过发送短信验证码方法发送短信验证码。

static Future<AuthResult> resetPasswordByPhoneCode(String phone, String code, String password) async

参数

phone 手机号
code 短信验证码
password 明文密码

示例

AuthResult result = await AuthClient.resetPasswordByPhoneCode("188xxxx8888", "code", "strong");
expect(result.code, 200);

错误码

2004 用户不存在

¶ 通过邮件验证码重置密码

通过邮件验证码重置密码，你需要先调用 sendEmail 接口发送重置密码邮件（场景值为 RESET_PASSWORD）。

static Future<AuthResult> resetPasswordByEmailCode(String email, String code, String password) async

参数

email 邮箱地址
code 邮件验证码
password 明文密码

示例

AuthResult result = await AuthClient.resetPasswordByEmailCode("test@example.com", "1234", "strong");
expect(result.code, 200);

错误码

2004 用户不存在

¶ 修改用户资料

修改用户资料，此接口不能用于修改手机号、邮箱、密码。

static Future<AuthResult> updateProfile(Map map) async

参数

object 需要修改的用户资料对象

可以通过此接口更新资料的字段：

username
nickname
company
photo
browser
device
name
givenName
familyName
middleName
profile
preferredUsername
website
gender
birthdate
zoneinfo
locale
address
streetAddress
locality
region
postalCode
city
province
country

示例

AuthResult result = await AuthClient.updateProfile({
  "username":"elonmusk",
  "nickname":"Ironman"
});

错误码

2020 未登录

¶ 更新用户密码

更新用户密码。如果用户没有设置密码，如通过短信验证码、社会化登录等方式注册的，oldPassword 留空。

static Future<AuthResult> AuthClient.updatePassword(String newPassword, [String? oldPassword])

参数

newPassword 新密码
oldPassword 旧密码。可以为空

示例

AuthResult result = await AuthClient.updatePassword("newPassword", "oldPassword");
var code = result.code;

错误码

2020 未登录
1320011 旧密码不正确

¶ 绑定手机号

为当前登录用户绑定手机号，调用发送短信验证码获取验证码。

static Future<AuthResult> bindPhone(String phone, String code) async

参数

phone 手机号
code 短信验证码

示例

AuthResult result = await AuthClient.bindPhone("188xxxx8888", "1234");
var code = result.code;

错误码

2020 未登录

¶ 解绑手机号

用户解绑手机号，如果用户没有绑定其他登录方式（邮箱、社会化登录账号），将无法解绑手机号，会提示错误。

static Future<AuthResult> unbindPhone() async

示例

AuthResult result = await AuthClient.unbindPhone();

错误码

2020 未登录
1320005 当前用户未绑定其他登录方式

¶ 更新手机号

更新手机号。可以在Authing控制台禁用旧电话号码验证，此时不传 oldPhone、oldPhoneCode 和 oldPhoneCountryCode

static Future<AuthResult> updatePhone(String phone, String phoneCode,
      [String? oldPhone,
      String? oldPhoneCode,
      String? phoneCountryCode,
      String? oldPhoneCountryCode]) async

参数

phone 手机号
code 短信验证码
oldPhone 旧手机号。可以为空
oldPhoneCode 旧手机号短信验证码。可以为空
phoneCountryCode 电话国家码。可以为空
oldPhoneCountryCode 旧手机号电话国家码。可以为空

示例

AuthResult result = await AuthClient.unbindPhone();

错误码

2020 未登录
1320004 当前手机号已绑定其他用户

¶ 绑定邮箱

为当前登录用户绑定邮箱，调用发送邮件获取验证码。

static Future<AuthResult> bindEmail(String email, String code) async

参数

email 邮箱地址
code 邮件验证码

示例

AuthResult result = await AuthClient.bindEmail("test@example.com", "1234");
var code = result.code;

错误码

2020 未登录

¶ 解绑邮箱

用户解绑邮箱，如果用户没有绑定其他登录方式（手机号、社会化登录账号），将无法解绑邮箱，会提示错误。

static Future<AuthResult> unbindEmail() async

示例

AuthResult result = await AuthClient.unbindEmail();

错误码

2020 未登录
1320005 当前用户未绑定邮箱

¶ 更新邮箱

更新邮箱。在Authing控制台可以禁用旧的邮箱验证，此时不传 oldEmail 和 oldEmailCode 。

static Future<AuthResult> updateEmail(String email, String emailCode,
      [String? oldEmail,
      String? oldEmailCode) async

参数

email 邮箱地址
code 邮件验证码
oldEmail 旧邮箱地址。可以为空
oldEmailCode 旧邮件验证码。可以为空

示例

AuthResult result = await AuthClient.updateEmail("test@example.com", "1234");

错误码

2020 未登录
1320004 当前邮箱已绑定其他用户

¶ 合并账号身份信息

将一个 Authing 子账号的外部身份源（如微信、GitHub、自定义 OIDC 身份源等）身份信息合并到一个 Authing 主账号上，同时删除子账号。

若用户原先使用某一身份源可以登录到子账号，合并之后，用户再用此身份源登录，将登录到主账号。

注意，除来自外部身份源的身份信息外，子账号的一切信息都会在合并后丢失！

static Future<AuthResult> link(String primaryUserToken, String secondaryUserToken) async

参数

primaryUserToken 主账号 Token
secondaryUserToken 子账号 Token

示例

AuthResult result = await AuthClient.link("first_token", "second_token");

错误码

2020 未登录
1320004 当前邮箱已绑定其他用户

¶ 计算密码安全等级

计算密码安全等级，返回三种级别的枚举类型：

0 等级低
1 等级中
2 等级高

static int computePasswordSecurityLevel(String password)

示例

AuthClient.computePasswordSecurityLevel("123"); // 0

¶ 获取用户账号安全等级

获取当前登录帐号的安全等级。

static Future<Result> getSecurityLevel() async

示例

Result result = await AuthClient.getSecurityLevel();
int score = result.data["score"];

回调 data 数据结构

{
    "code": 200,
    "message": "请求成功",
    "data": {
        "score": 60,
        "email": false,
        "phone": false,
        "password": true,
        "passwordSecurityLevel": 1,
        "mfa": false
    }
}

错误码

2020 未登录

¶ 刷新当前用户的 ID Token

static Future<AuthResult> updateIdToken() async

示例

Map result = await AuthClient.updateIdToken();

错误码

2020 未登录

¶ 获取当前用户能够访问的应用

获取当前用户能够访问的应用。注意返回的结果数据结构为 NSArray。

static Future<Result> listApplications([int? page = 1, int? limit = 10]) async

参数

page 分页序号, 默认为 1。
limit 每页返回的个数, 默认为 10。

示例

Result result = await AuthClient.listApplications();
int count = result.data["totalCount"];

返回结果示例

{
    "code": 200,
    "message": "获取可访问的应用列表成功",
    "data": {
        "list": [
            {
                "id": "61ae0c9807451d6f30226bd4",
                "name": "lance-test",
                "logo": "https://files.authing.co/authing-console/default-app-logo.png",
                "domain": "lance-test",
                "description": null,
                "createdAt": "2021-12-06T13:14:01.123Z",
                "updatedAt": "2022-01-20T10:51:02.806Z",
                "protocol": "oidc",
                "isIntegrate": false,
                "appType": "INDIVIDUAL",
                "template": null
            }
        ],
        "totalCount": 1
    }
}

错误码

2020 未登录

¶ 获取用户所在组织机构

获取用户所在组织机构。由于用户可以在多个独立的组织机构树下，所以本接口返回了一个二位数组。注意返回的结果数据结构为 NSArray。

static Future<Result> listOrgs() async

示例

Result result = await AuthClient.listOrgs();
List list = result.data["data"]; // note double data

返回结果示例

String name = list[0][3]["name"]; // 返回第一层，第四级部门的名称

错误码

2020 未登录

¶ 获取角色

获取当前登录用户的角色。注意返回的数据结构为 NSArray。

static Future<Result> listRoles([String? namespace]) async

参数

namespace 权限分组 ID，用来过滤角色数据。如果传空，则返回用户所有角色

示例

Result result = await AuthClient.listRoles();
List list = result.data["data"]; // note double data

返回结果示例

{
    "code": 200,
    "message": "获取成功",
    "data": [
        {
            "id": "61ada935ce061fe3476f0f09",
            "createdAt": "2021-12-06T06:09:57.523Z",
            "updatedAt": "2021-12-06T06:09:57.523Z",
            "userPoolId": "60caaf41da89f1954875cee1",
            "code": "admin",
            "description": null,
            "parentCode": null,
            "isSystem": false,
            "namespaceId": 36141,
            "namespace": "60caaf414f9323f25f64b2f4"
        }
    ]
}

错误码

2020 未登录

¶ 获取用户被授权的所有资源列表

获取一个用户被授权的所有资源，用户被授权的所有资源里面包括从角色、分组、组织机构继承的资源。

static Future<Map> listAuthorizedResources(String namespace, [String? resourceType]) async

参数

namespace 权限分组 ID
resourceType 资源类型。可以为以下几种类型 DATA, API, MENU, UI, BUTTON。如果传空，则返回所有资源类型数据

示例

Map result = await AuthClient.listAuthorizedResources("default");
String result["list"][0]["code"];

返回结果示例

{
    "totalCount": 1,
    "list": [
        {
            "code": "ci:*",
            "type": "DATA",
            "actions": [
                "*"
            ],
            "apiIdentifier": null
        }
    ]
}

错误码

2020 未登录

¶ 首次登录重置密码

在 Authing 控制台启用该功能后，用户首次登录后必须重置密码。

static Future<AuthResult> resetPasswordByFirstLoginToken(String token, String password) async

参数

token 首次登录后返回
password 密码

示例

AuthResult result = await AuthClient.resetPasswordByFirstLoginToken("token", "strong");

上一篇: 快速开始下一篇: 标准协议 API