authing_sdk

Description:

authing sdk

Getting started #
Add dependency #
in your pubspec.yaml, add the following dependency:
authing_sdk: ^1.0.0
copied to clipboard
SDK initialization #
Upon App start, call:
import 'package:authing_sdk/authing.dart';

Authing.init(String userPoolId, String appId)
copied to clipboard
where userPoolId is your Authing user pool id and appId is your Authing app id
On-premise deployment #
for on-premise deployments, after calling init, call:
Authing.setOnPremiseInfo(String host, String publicKey)
copied to clipboard
where host is your own domain, e.g. mycompany.com and publicKey is your organization's public key.
Contact Authing sales if you have any questions.

APIs #
Basic Authentication #

Register by email
Register by user name
Register by phone code
Login by account and password
Login by phone code
Login by LDAP
Login by AD
Get current user
Logout
Send SMS code
Send email
Get user custom data
Set user custom data
Reset password by phone code
Reset password by email code
Update user profile
Update password
Bind phone
Unbind phone
Update phone
Bind email
Unbind email
Update email
Link
Unlink
Compute password security level
Get security level
List applications
List organizations
List roles
List authorized resources
Update id token
Reset password by first time login token

Social #

Login by wechat
Login by alipay
Login by apple

MFA #

MFA check
MFA verify by phone
MFA verify by email
MFA verify by TOTP
MFA verify by recovery code

OIDC #

Login by OIDC authorization code
OIDC Login by account and password
OIDC Login by phone code
Build authorize URL
Token Change user information
Refresh Access Token

Scan #

mark QR code scanned
login by QR code


Authentication API #
for all authentication APIs, you should import:
import 'package:authing_sdk/client.dart';
copied to clipboard

Register by email #
Register a new user by email. The email is case insensitive and must be unique within a given user pool. After registration, emailVerified is false.
static Future<AuthResult> registerByEmail(String email, String password) async
copied to clipboard
params

email
password clear text password

example
AuthResult result = await AuthClient.registerByEmail("[email protected]", "strong");
User user = result.user;
copied to clipboard
error

2003 if email address is mal-formatted
2026 if email has been registered already


Register by user name #
Register a new user by user name. User name is case sensitive and must be unique within a given user pool.
static Future<AuthResult> registerByUserName(String username, String password) async
copied to clipboard
params

username
password clear text password

example
AuthResult result = await AuthClient.registerByUserName("nextgeneration", "strong");
User user = result.user;
copied to clipboard
error

2026 if username has been registered already


Register by phone code #
Register a new user by phone number and a verification code. Phone number must be unique within a given user pool.
Must call sendSms method to get an SMS verification code before calling this method.
static Future<AuthResult> registerByPhoneCode(String phone, String code, String password, {String? phoneCountryCode}) async
copied to clipboard
params

phone phone number
code SMS code
password clear text password
phoneCountryCode country code

example
AuthResult result = await AuthClient.registerByPhoneCode("13012345678", "1121", "strong", phoneCountryCode: "+86");
User user = result.user;
copied to clipboard
error

2001 if verification code is incorrect
2026 if phone number has been registered already


Login by account and password #
static Future<AuthResult> loginByAccount(String account, String password) async
copied to clipboard
params

account can be one of the following: phone number / email / user name
password clear text password

example
AuthResult result = await AuthClient.loginByAccount("your account", "your password");
User user = result.user; // user info
copied to clipboard
error

2333 incorrect credential


Login by phone code #
login by phone number and a verification code. Must call sendSms method to get an SMS verification code before calling this method.
static Future<AuthResult> loginByPhoneCode(String phone, String code, {String? phoneCountryCode}) async
copied to clipboard
params

phone phone number
code SMS code
phoneCountryCode country code

example
AuthResult result = await AuthClient.loginByPhoneCode("13012345678", "1234", phoneCountryCode: "+86");
User user = result.user; // get user info
copied to clipboard
error

2001 if verification code is incorrect


Login by LDAP #
static Future<AuthResult> loginByLDAP(String username, String password) async
copied to clipboard
params

username ldap username
password clear text password

example
AuthResult result = await AuthClient.loginByLDAP("your username", "your password");
User user = result.user; // user info
copied to clipboard
error

2333 incorrect credential


Login by AD #
static Future<AuthResult> loginByAD(String username, String password) async
copied to clipboard
params

username AD username
password clear text password

example
AuthResult result = await AuthClient.loginByAD("your username", "your password");
User user = result.user; // user info
copied to clipboard
error

2333 incorrect credential


Get current user #
Get current user information. Must log in first.
static Future<AuthResult> getCurrentUser() async
copied to clipboard
example
AuthResult result = await AuthClient.getCurrentUser();
User user = result.user; // user info
copied to clipboard
error

2020 must login first


Logout #
Logout user.
static Future<AuthResult> logout() async
copied to clipboard
example
AuthResult result = await AuthClient.logout();
var code = result.code;
copied to clipboard
error

1010001 if token is invalid or expired


Send SMS code #
Send an SMS verification code
static Future<AuthResult> sendSms(String phone, [String? phoneCountryCode]) async
copied to clipboard
params

phone phone number to receive the code
phoneCountryCode phone country code starts with +. Optional

example
AuthResult result = await AuthClient.sendSms("13012345678", "+86");
var code = result.code;
copied to clipboard
error

500 phone number is mal-formatted


Send email #
Send an email to the given email addrees
static Future<AuthResult> sendEmail(String email, String scene) async
copied to clipboard
params

email email address
scene can be one of the following: RESET_PASSWORD, VERIFY_EMAIL, CHANGE_EMAIL, MFA_VERIFY

example
AuthResult result = await AuthClient.sendEmail("[email protected]", "RESET_PASSWORD");
var code = result.code;
copied to clipboard
error

1020017 email address is mal-formatted


Get user custom data #
Firstly add custom field in authing console, then use this API to retrieve user custom data. You can pass AuthClient.currentUser!.id as the user id param. Upon success, custom data will be added in AuthClient.currentUser?.customData
Must log in first
static Future<AuthResult> getCustomData(String userId) async
copied to clipboard
params

userId user id received after login

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

2020 must log in first


Set user custom data #
Firstly add custom field in authing console, then use this API to set user custom data.
Must log in first
static Future<AuthResult> setCustomData(List data) async
copied to clipboard
params

data a list of custom data that needs to be modified. The easy way is firstly set custom data value in your user object, then pass user object's customData field as parameter.

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

2020 must log in first


Reset password by phone code #
Reset user password using email verification code. Must call sendSms method to get an SMS verification code before calling this method.
static Future<AuthResult> resetPasswordByPhoneCode(String phone, String code, String password) async
copied to clipboard
params

phone phone number
code SMS verification code
password clear text password

example
AuthResult result = await AuthClient.resetPasswordByPhoneCode("13012345678", "1234", "strong");
expect(result.code, 200);
copied to clipboard
error

2004 user not exist


Reset password by email code #
Reset user password using SMS verification code. Must call sendEmail method with scene "RESET_PASSWORD" to get an emmail verification code before calling this method.
static Future<AuthResult> resetPasswordByEmailCode(String email, String code, String password) async
copied to clipboard
params

email email address
code email verification code
password clear text password

example
AuthResult result = await AuthClient.resetPasswordByEmailCode("[email protected]", "1234", "strong");
expect(result.code, 200);
copied to clipboard
error

2004 user not exist


Update user profile #
Update user profile. Note phone, email and password cannot be updated using this method. Please call updatePhone / updateEmail / updatePassword respectively.
Must log in first.
static Future<AuthResult> updateProfile(Map map) async
copied to clipboard
params

map user data needs to be updated

full list of field that can be used as key in the map parameter

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

example
AuthResult result = await AuthClient.updateProfile({
"username":"elonmusk",
"nickname":"Ironman"
});
copied to clipboard
error

2020 must log in first


Update password #
Update user password. Must log in first. In case user didn't set a password (e.g. registered by phone code or social connections), the old password parameter should be omitted.
static Future<AuthResult> AuthClient.updatePassword(String newPassword, [String? oldPassword])
copied to clipboard
params

newPassword new password in clear text
oldPassword old password in clear text. Optional

example
AuthResult result = await AuthClient.updatePassword("newPassword", "oldPassword");
var code = result.code;
copied to clipboard
error

2020 must log in first
1320011 old password is incorrect


Bind phone #
Bind phone number for current user. If already bound, use updatePhone instead.
Must log in first
static Future<AuthResult> bindPhone(String phone, String code) async
copied to clipboard
params

phone phone number
code SMS code

example
AuthResult result = await AuthClient.bindPhone("13012345678", "1234");
var code = result.code;
copied to clipboard
error

2020 must log in first


Unbind phone #
Unbind phone number for current user.
Must log in first
static Future<AuthResult> unbindPhone() async
copied to clipboard
example
AuthResult result = await AuthClient.unbindPhone();
copied to clipboard
error

2020 must log in first
1320005 current user has no phone number bound


Update phone #
Update phone number for current user. Old phone number verification can be disabled in Authing console, in such case, oldPhone, oldPhoneCode and oldPhoneCountryCode must be omitted.
Must log in first
static Future<AuthResult> updatePhone(String phone, String phoneCode,
[String? oldPhone,
String? oldPhoneCode,
String? phoneCountryCode,
String? oldPhoneCountryCode]) async
copied to clipboard
params

phone new phone number
code SMS code sent to the new phone
oldPhone old phone number. Optional
oldPhoneCode SMS code sent to old phone. Optional
phoneCountryCode phone country code for the new phone. Optional
oldPhoneCountryCode phone country code for the old phone. Optional

example
AuthResult result = await AuthClient.updatePhone("13012345678", "1234");
copied to clipboard
error

2020 must log in first
1320004 phone already bound by other user


Bind email #
Bind email address for current user. If already bound, use updateEmail instead.
Must log in first
static Future<AuthResult> bindEmail(String email, String code) async
copied to clipboard
params

email email address
code email verification code

example
AuthResult result = await AuthClient.bindEmail("[email protected]", "1234");
var code = result.code;
copied to clipboard
error

2020 must log in first


Unbind email #
Unbind email address for current user.
Must log in first
static Future<AuthResult> unbindEmail() async
copied to clipboard
example
AuthResult result = await AuthClient.unbindEmail();
copied to clipboard
error

2020 must log in first
1320005 current user has no email bound


Update email #
Update email address for current user. Old email address verification can be disabled in Authing console, in such case, oldEmail and oldEmailCode must be omitted.
Must log in first
static Future<AuthResult> updateEmail(String email, String emailCode,
[String? oldEmail,
String? oldEmailCode) async
copied to clipboard
params

email email address
code email verification code
oldEmail old email address. Optional
oldEmailCode email code sent to old email. Optional

example
AuthResult result = await AuthClient.updateEmail("[email protected]", "1234");
copied to clipboard
error

2020 must log in first
1320004 email already bound by other user


Link #
Links current account with another social account.
Must log in first
static Future<AuthResult> link(String primaryUserToken, String secondaryUserToken) async
copied to clipboard
params

primaryUserToken current user's token
secondaryUserToken the target social account's token. Note this token is still Authing token.

example
AuthResult result = await AuthClient.link("first_token", "second_token");
copied to clipboard
error

2020 must log in first
1020020 token is not valid


Unlink #
Unlinks current account with a social account.
Must log in first
static Future<AuthResult> unlink(String provider) async
copied to clipboard
params

provider type of the social account

example
AuthResult result = await AuthClient.unlink("wechat:mobile");
copied to clipboard
error

2004 user not exist


Compute password security level #
Computes the security level for a givenn password and return:

0 low
1 medium
2 high

static int computePasswordSecurityLevel(String password)
copied to clipboard
example
AuthClient.computePasswordSecurityLevel("123"); // 0
copied to clipboard

Get security level #
The current account's security level. Note that the result is not AuthResult, it is a general Result oject.
Must log in first
static Future<Result> getSecurityLevel() async
copied to clipboard
example
Result result = await AuthClient.getSecurityLevel();
int score = result.data["score"];
copied to clipboard
return
{
"code": 200,
"message": "请求成功",
"data": {
"score": 60,
"email": false,
"phone": false,
"password": true,
"passwordSecurityLevel": 1,
"mfa": false
}
}
copied to clipboard
error

2020 must log in first


List applications #
Get all applications that the current user has access. Note that the result is not AuthResult, it is a general Result oject.
Must log in first
static Future<Result> listApplications([int? page = 1, int? limit = 10]) async
copied to clipboard
params

page page index. Optional
limit number of applications returned in one page. Optional

example
Result result = await AuthClient.listApplications();
int count = result.data["totalCount"];
copied to clipboard
return
{
"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
}
}
copied to clipboard
error

2020 must log in first


List organizations #
Get all organizations that the current user is in. Note that the result is not AuthResult, it is a general Result oject.
Must log in first
static Future<Result> listOrgs() async
copied to clipboard
example
Result result = await AuthClient.listOrgs();
List list = result.data["data"]; // note double data
copied to clipboard
return
Since user can be part of separated oragnization trees, this method returns a two-dimensional list stored in result.data["data"]. For example to access one department, do it like this:
String name = list[0][3]["name"]; // returns the first tree, level 4 department's name
copied to clipboard
error

2020 must log in first


List roles #
Get roles of current user. Note that the result is not AuthResult, it is a general Result oject.
Must log in first
static Future<Result> listRoles([String? namespace]) async
copied to clipboard
params

namespace namespace id to filter the result. Optional

example
Result result = await AuthClient.listRoles();
List list = result.data["data"]; // note double data
copied to clipboard
return
{
"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"
}
]
}
copied to clipboard
error

2020 must log in first


List authorized resources #
Get authorized resources of current user. Note that the result is a Map.
Must log in first
static Future<Map> listAuthorizedResources(String namespace, [String? resourceType]) async
copied to clipboard
params

namespace namespace id to filter the result
resourceType resource type to filter the result. Can be DATA, API, MENU, UI, BUTTON. Optional

example
Map result = await AuthClient.listAuthorizedResources("default");
String result["list"][0]["code"];
copied to clipboard
return
{
"totalCount": 1,
"list": [
{
"code": "ci:*",
"type": "DATA",
"actions": [
"*"
],
"apiIdentifier": null
}
]
}
copied to clipboard
error

2020 must log in first


Update id token #
Get new id token using current user's id token
Must log in first
static Future<AuthResult> updateIdToken() async
copied to clipboard
example
Map result = await AuthClient.updateIdToken();
copied to clipboard
error

2020 must log in first


Reset password by first time login token #
If this feature is enabled, user must reset password after first time login
static Future<AuthResult> resetPasswordByFirstLoginToken(String token, String password) async
copied to clipboard
params

token returned after initial login
password clear text password

example
AuthResult result = await AuthClient.resetPasswordByFirstLoginToken("token", "strong");
copied to clipboard

Social API #
Login by wechat #
Login by wechat auth code
static Future<AuthResult> loginByWechat(String connId, String code) async
copied to clipboard
params

connId get from social connection config in Authing console
code auth code returned by wechat

example
AuthResult result = await AuthClient.loginByAccount("connId", "code");
copied to clipboard

Login by alipay #
Login by alipay auth code
static Future<AuthResult> loginByAlipay(String connId, String code) async
copied to clipboard
params

connId get from social connection config in Authing console
code auth code returned by alipay

example
AuthResult result = await AuthClient.loginByAlipay("connId", "code");
copied to clipboard

Login by apple #
Login by apple auth code
static Future<AuthResult> loginByApple(String code) async
copied to clipboard
params

code auth code returned by apple

example
AuthResult result = await AuthClient.loginByApple("code");
copied to clipboard

MFA API #
MFA check #
Checks if a given phone or email can be used for MFA
static Future<bool> mfaCheck(String? phone, String? email) async
copied to clipboard
params

phone phone number to check. Can be null
email email address to check. Can be null

example
bool r1 = await AuthClient.mfaCheck("13012345678", null);
bool r2 = await AuthClient.mfaCheck(null, "[email protected]");
copied to clipboard

MFA verify by phone #
MFA by SMS verification code sent to phone
static Future<AuthResult> mfaVerifyByPhone(String phone, String code) async
copied to clipboard
params

phone phone number
code SMS verification code

example
AuthResult result = await AuthClient.mfaVerifyByPhone("13012345678", "1234");
copied to clipboard

MFA verify by email #
MFA by email verification code
static Future<AuthResult> mfaVerifyByEmail(String email, String code) async
copied to clipboard
params

email email address
code email verification code

example
AuthResult result = await AuthClient.mfaVerifyByEmail("[email protected]", "1234");
copied to clipboard

MFA verify by TOTP #
MFA by TOTP (Time-based One Time Password) code. User must firstly bound with TOTP.
static Future<AuthResult> mfaVerifyByTOTP(String code) async
copied to clipboard
params

code TOTP code

example
AuthResult result = await AuthClient.mfaVerifyByTOTP("1234");
copied to clipboard

MFA verify by recovery code #
MFA by recovery code which should be safely stored after first time bound with TOTP. Note after successful MFA via this method, the recovery code will be refreshed and returned by this method. User should again safely store the new recovery code.
static Future<AuthResult> mfaVerifyByRecoveryCode(String code) async
copied to clipboard
params

code recovery code

example
AuthResult result = await AuthClient.mfaVerifyByRecoveryCode("1234");
copied to clipboard

OIDC API #
Auth by code #
After OIDC authentication, we will get an authorization code. Use this API to get user's access token & id token. Note that since we are front end, we cannot set OIDC client secret, instead, we have to use PKCE to get the code.
static Future<AuthResult> authByCode(String code, String codeVerifier, String redirectUrl) async
copied to clipboard
params

code authorization code
codeVerifier PKCE code verifier
redirectUrl a valid url set in Authing console

example
AuthResult result = await AuthClient.authByCode("P6FENDfGSH72PxgJQk17FoGMWY3oL1G0D2PQ1AfyDeo",
"fu6IivbcEb7DFCytjLmoAICRtFLbG9zkk5QdDbNd0gG",
"https://guard.authing/redirect");
String ak = result.user?.accessToken;
String idToken = result.user?.token;
copied to clipboard

OIDC Login by account and password #
static Future<AuthResult> loginByAccount(String account, String password) async
copied to clipboard
params

account can be one of the following: phone number / email / user name
password clear text password

example
AuthResult results = await OIDCClient.loginByAccount("your account", "your password");
User user = results.user; // user info
copied to clipboard

OIDC Login by phone code #
login by phone number and a verification code. Must call sendSms method to get an SMS verification code before calling this method.
static Future<AuthResult> loginByPhoneCode(String phone, String code, {String? phoneCountryCode}) async
copied to clipboard
params

phone phone number
code SMS code
phoneCountryCode country code

example
AuthResult result = await OIDCClient.loginByPhoneCode("phone", "code");
User user = result.user; // get user info
copied to clipboard

Build authorize URL #
The buildAuthorizeUrl method can be used to build the login URL, load the URL in your WebView.
static Future<AuthResult> buildAuthorizeUrl(AuthRequest authRequest) async
copied to clipboard
params

authRequest Sets the custom parameters.Valid parameters include 'scope','redirectUrl','state'.For a detailed list, check the AuthRequest().

example
AuthRequest authRequest = AuthRequest();
authRequest.createAuthRequest();
// authRequest.scope = "scope";
// authRequest.redirectUrl = "redirectUrl";
String url = await OIDCClient.buildAuthorizeUrl(authRequest);
copied to clipboard

Token Change user information #
Use Access token to get user information.
static Future<Result> getUserInfoByAccessToken(String accessToken, [Map? data]) async
copied to clipboard
params

accessToken Access token

example
Result result = await OIDCClient.getUserInfoByAccessToken("accessToken");
copied to clipboard

Refresh Access Token #
Get new Access Token with Refresh token.
static Future<AuthResult> getNewAccessTokenByRefreshToken(String refreshToken) async
copied to clipboard
params

refreshToken Refresh Token

example
AuthResult result = await OIDCClient.getNewAccessTokenByRefreshToken("refreshToken");
User user = result.user; // get user info
copied to clipboard

Scan API #
In order to support scan-to-login feature, first enable it in Authing console, then in the login web page, a QR code will be shown to user. User will then use your in house app to scan the QR code and if success, the web site will be logged in by the account that was logged into the in house app. As the flow suggests, user must firstly log into your in house app using any login method provided by this SDK.
Authing QR code data structure:
{
"scene": "APP_AUTH",
"random": "5e05f0c57fde537d950f7da5",
"userPoolId": "5e04ae0d5f3cee22fb37612b",
"createdAt": "2019-12-27T11:53:41.260Z",
"expireAt": "2019-12-27T11:55:41.260Z",
"customData": { "hello": "world" }
}
copied to clipboard
mark QR code scanned #
After calling this API, the web page will show user avatar on top of the QR code

Must call one of the login method first so that we have a logged in user

static Future<Result> markQRCodeScanned(String ticket) async
copied to clipboard
params

ticket random field in QR code data structure

example
Result result = await AuthClient.markQRCodeScanned(ticket);
copied to clipboard

login by QR code #
Login the web application by the QR code that has been shown to user

Must call mark QR code scanned first before calling this API

static Future<Result> loginByScannedTicket(String ticket) async
copied to clipboard
params

ticket random field in QR code data structure

example
Result result = await AuthClient.loginByScannedTicket(random);
copied to clipboard