Login using user credentials

This document is automatically generated based on https://github.com/authing/authing-docs-factory based on the https://api-explorer.genauth.ai V3 API, and is consistent with the API parameters and return results. If this document description is incorrect, please refer to the V3 API.

This endpoint is a login endpoint based on direct API calls, which is suitable for scenarios where you need to build your own login page. ** This endpoint does not currently support MFA, information completion, first password reset and other processes. If necessary, please use the OIDC standard protocol authentication endpoint. **

Note: Depending on the ** application type ** you selected when creating the application in GenAuth and the ** token exchange authentication method ** configured in the application, different forms of verification of the client's identity are required when calling this interface.

Click to expand details

You can find the Exchange token authentication method configuration item in Application - Self-built application - Application details - Application configuration - Other settings - Authorization configuration in the GenAuth console:

Single-page web applications and client applications are hidden, and the default value is none, which is not allowed to be modified; backend applications and standard web applications can modify this configuration item.

When the exchange token authentication method is none

No additional operations are required to call this interface.

When the exchange token authentication method is client_secret_post

When calling this interface, the client_id and client_secret parameters must be passed in the body as conditions for verifying the client's identity. Among them, client_id is the application ID, and client_secret is the application secret key.

When exchanging token authentication mode is client_secret_basic

When calling this interface, the authorization request header must be carried in the HTTP request header as a condition for verifying the client identity. The format of the authorization request header is as follows (where client_id is the application ID and client_secret is the application secret key):

Basic base64(<client_id>:<client_secret>)

Result example:

Basic NjA2M2ZiMmYzY3h4eHg2ZGY1NWYzOWViOjJmZTdjODdhODFmODY3eHh4eDAzMjRkZjEyZGFlZGM3

JS code example:

"Basic " + Buffer.from(client_id + ":" + client_secret).toString("base64");

Method Name

AuthenticationClient.signInByCredentials

Request Parameters

Name	Type	Required	Default Value	Description	Example Value
connection	string	yes	-	Authentication method: - PASSWORD: Use password for authentication. - PASSCODE: Use one-time temporary verification code for authentication. - LDAP: Authentication based on LDAP user directory. - AD: Authentication based on Windows AD user directory.	PASSWORD
passwordPayload	<a SignInByPasswordPayloadDto	no	-	This parameter is required when the authentication method is PASSWORD.	{"email":"test@example.com","password":"passw0rd"}
passCodePayload	<a SignInByPassCodePayloadDto	No	-	This parameter is required when the authentication method is PASSCODE	{"email":"test@example.com","passCode":"passw0rd"}
adPayload	<a SignInByAdPayloadDto	No	-	This parameter is required when the authentication method is AD	{"sAMAccountName":"test","password":"passw0rd"}
ldapPayload	<a SignInByLdapPayloadDto	No	-	This parameter is required when the authentication method is LDAP	{"sAMAccountName":"test","password":"passw0rd"}
options	<a SignInOptionsDto	No	-	Optional parameters	{"passwordEncryptType":"none"}
client_id	string	No	-	Application ID. Required when the application's "Exchange token authentication method" is configured as client_secret_post.	6342b8537axxxx047d314109
client_secret	string	No	-	Application secret key. Required when the application's "Exchange token authentication method" is configured as client_secret_post.	4203d30e5e915xxxxxx26c31c9adce68

Example Code

import { AuthenticationClient, Models } from "authing-node-sdk";

const authenticationClient = new AuthenticationClient({
  // Need to be replaced with your GenAuth AppId, Secret and Host
  appId: "GEN_AUTH_APP_ID",
  appSecret: "GEN_AUTH_APP_SECRET",
  appHost: "GEN_AUTH_APP_HOST",
});

(async () => {
  const result = await authenticationClient.signInByCredentials({
    connection: Models.SigninByCredentialsDto.connection.PASSWORD,
    passwordPayload: {
      password: "passw0rd",
      email: "test-user@example.com",
    },
    client_id: "GEN_AUTH_APP_ID",
    client_secret: "GEN_AUTH_APP_SECRET",
  });

  console.log(JSON.stringify(result, null, 2));
})();

Request Response

type: LoginTokenRespDto

Name	Type	Description
statusCode	number	Business status code, which can be used to determine whether the operation is successful. 200 means success.
message	string	Description
apiCode	number	Segmented error code, which can be used to get the specific error type (successful request does not return). For a detailed list of error codes, please see: API Code List
requestId	string	Request ID. Returned when the request fails.
data	<a LoginTokenResponseDataDto	Response data

Sample result:

{
  "statusCode": 200,
  "message": "Success",
  "requestId": "934108e5-9fbf-4d24-8da1-c330328abd6c",
  "data": {
    "scope": "openid profile",
    "access_token": "eyJhbGciOiJSxxxxx",
    "id_token": "eyJhbGxxxx",
    "refresh_token": "WPsGJbvpBjqXz6IJIr1UHKyrdVF",
    "token_type": "bearer",
    "expire_in": 7200
  }
}

Data Structure

SignInByPasswordPayloadDto

Name	Type	Is this field required?	Description	Sample value
password	string	yes	User password, unencrypted by default. All GenAuth APIs transmit passwords securely via the HTTPS protocol, which can ensure security to a certain extent. If you need a higher level of security, we also support RSA256 and the national secret SM2 password encryption methods. For details, see the optional parameter options.passwordEncryptType.	passw0rd
account	string	no	User account (username/mobile number/email)	test
email	string	no	Email, case-insensitive.	test@example.com
username	string	no	Username (username)	test
phone	string	no	Mobile number	188xxxx8888

SignInByPassCodePayloadDto

Name	Type	Is this field required?	Description	Sample value
passCode	string	yes	A one-time temporary verification code. You need to first call the send SMS or send email interface to obtain the verification code.	123456
email	string	no	Email address, case insensitive.	114114
phone	string	no	Mobile phone number	188xxxx8888
phoneCountryCode	string	no	Mobile phone area code. This field is optional for mobile phone numbers in mainland China. The GenAuth SMS service does not currently support international mobile phone numbers. You need to configure the corresponding international SMS service in the GenAuth console. For a complete list of mobile phone area codes, please refer to https://en.wikipedia.org/wiki/List_of_country_calling_codes.	+86

SignInByAdPayloadDto

Name	Type	Required	Description	Sample value
password	string	Yes	User password, unencrypted by default. All GenAuth APIs transmit passwords securely via HTTPS, which can ensure security to a certain extent. If you need a higher level of security, we also support RSA256 and national secret SM2 password encryption methods. For details, see the optional parameter options.passwordEncryptType.	passw0rd
sAMAccountName	string	Yes	sAMAccountName of the account in the Windows AD user directory	test

SignInByLdapPayloadDto

Name	Type	Is it required?	Description	Sample value
password	string	Yes	User password, unencrypted by default. All GenAuth APIs transmit passwords securely via HTTPS, which can ensure security to a certain extent. If you need a higher level of security, we also support RSA256 and national secret SM2 password encryption methods. For details, see the optional parameter options.passwordEncryptType.	passw0rd
sAMAccountName	string	Yes	sAMAccountName of the account in the LDAP AD user directory	114114

SignInOptionsDto

Name	Type	Is this field required?	Description	Sample value
scope	string	no	The permissions that need to be requested, must include openid. If you need to obtain the mobile phone number and email, you need to include phone email; if you need refresh_token, you need to include offline_access. Please separate multiple scopes with spaces. The decoded content of id_token will contain the user information related fields corresponding to these scopes. - openid: Must be included. - profile: Returns birthdate, family_name, gender, given_name, locale, middle_name, name, nickname, picture, preferred_username, profile, updated_at, website, zoneinfo fields. - username: Returns username. - email: Returns email, email_verified. - phone: Returns phone_number, phone_number_verified. - offline_access: If this parameter exists, the token interface will return the refresh_token field. - roles: Returns the user's role list. - external_id: User ID of the user in the original system. - extended_fields: Returns the user's extended field information, the content is an object, the key is the extended field name, and the value is the extended field value. - tenant_id: Returns the user's tenant ID.	openid profile
clientIp	string	No	The real IP address of the client. By default, GenAuth will identify the IP address of the request source as the IP address of the user's login. If you call this interface in the backend server, you need to set this IP to the user's real request IP.	192.168.0.1
context	object	No	Additional request context, which will be passed to the context object of the Pipeline before and after authentication. Learn how to get additional context passed in to the context parameter of a Pipeline.	{"source":"utm"}
tenantId	string	no	tenant ID	625783d629f2bd1f5ddddd98c
customData	object	No	To set additional user custom data, you need to configure custom data in the GenAuth console first.	{"school":"pku","age":"20"}
autoRegister	boolean	No	Whether to enable automatic registration. If set to true, an account will be automatically created for the user if it does not exist. Note: This parameter is only valid for the specified username and password, email password, and mobile phone number password. This parameter cannot be set for general account passwords.
captchaCode	string	No	Captcha graphic verification code, case-insensitive. When the security policy is set to verification code and the login failure limit is triggered, the graphic verification code needs to be filled in the next login.	a8nz
passwordEncryptType	string	No	Password encryption type, supports RSA256 and SM2 algorithms. The default is none, no encryption. - none: Do not encrypt the password, use plain text for transmission. - rsa: Use RSA256 algorithm to encrypt the password, and need to use the RSA public key of the GenAuth service for encryption. Please read the Introduction section to learn how to obtain the RSA256 public key of the GenAuth service. - sm2: Use SM2 algorithm to encrypt the password, and need to use the SM2 public key of the GenAuth service for encryption. Please read the Introduction section to learn how to obtain the SM2 public key of the GenAuth service.	sm2

LoginTokenResponseDataDto

Name	Type	Is this field required?	Description	Sample value
scope	string	no	Scope corresponding to access_token	openid profile
access_token	string	no	API call credentials, authorized to access resource API within a limited time	eyJhbGciOiJSxxxxx
id_token	string	no	User's identity credentials, which will contain user information after parsing	eyJhbGxxxx
refresh_token	string	no	refresh_token is used to obtain a new AccessToken	WPsGJbvpBjqXz6IJIr1UHKyrdVF
token_type	string	yes	Token type	bearer
expire_in	number	yes	Expiration time in seconds	7200
4203d30e5e915xxxxxx26c31c9adce68	## Sample code

import { AuthenticationClient, Models } from "authing-node-sdk"; const authenticationClient = new AuthenticationClient({ // Need to be replaced with your GenAuth AppId, Secret and Host appId: "GEN_AUTH_APP_ID", appSecret: "GEN_AUTH_APP_SECRET", appHost: "GEN_AUTH_APP_HOST", }); (async () => { const result = await authenticationClient.signInByCredentials({ connection: Models.SigninByCredentialsDto.connection.PASSWORD, passwordPayload: { password: "passw0rd", email: "test-user@example.com", }, client_id: "GEN_AUTH_APP_ID", client_secret: "GEN_AUTH_APP_SECRET",

});

console.log(JSON.stringify(result, null, 2));
})();

Request response type: LoginTokenRespDto

| Name| Type| Description| | ---------- | --------------------------------------- --------------------------- | ---------------------- -------------------------------------------------- -------------------------------------------------- -------------------------------------------------- -------------------------------------------------- -------------------------------------------- | | statusCode | number | Business status code, which can be used to determine whether the operation is successful. 200 means success. | | message | string | description information | | apiCode | number | Segment error code, which can be used to get the specific error type (successful request does not return). For a detailed list of error codes, please see: [API Code List](https://api-explorer.genauth.ai/?tag=group/开发准� %A4%87#tag/%E5%BC%80%E5%8F%91%E5%87%86%E5%A4%87/%E9%94%99%E8%AF%AF%E5%A4%84 %E7%90%86/apiCode) | | requestId | string | Request ID. Returned when the request fails. | | data | <a LoginTokenResponseDataDto | Response data|

Sample result:

{
"statusCode": 200,
"message": "Operation successful",
"requestId": " 934108e5-9fbf-4d24-8da1-c330328abd6c",
"data": {
"scope": "openid profile",
"access_token": "eyJhbGciOiJSxxxxx",
"id_token": "eyJhbGxxxx",
"refresh_token": "WPsGJbvpBjqXz6IJIr1UHKyrdVF",
" token_type": "bearer",
"expire_in": 7200
}
}

Data Structure### SignInByPasswordPayloadDto

Name	Type	Is it required?	Description	Example value
password	string	yes	User password, unencrypted by default. All GenAuth APIs use HTTPS protocol to securely transmit passwords, which can ensure security to a certain extent. If you need a higher level of security, we It also supports RSA256 and national encryption SM2 password encryption methods. See the optional parameter options.passwordEncryptType for details.	passw0rd
account	string	No	User account (user name/phone number/email address)	test
email	string	No	Email address, case-insensitive.	test@example.com
username	string	No	Username	test
phone	string	No	Phone number	188xxxx8888

SignInByPassCodePayloadDto

Name	Type	Is it required?	Description	Sample value
passCode	string	Yes	One-time temporary verification code. You need to call the send SMS or send email interface to obtain the verification code first.	123456
email	string	No	Email address, case insensitive.	114114
phone	string	No	Mobile phone number	188xxxx8888
phoneCountryCode	string	No	Mobile phone area code. This field is optional for mobile phone numbers in mainland China. The GenAuth SMS service does not yet support international mobile phone numbers. You need to configure the corresponding international SMS service in the GenAuth console. For a complete list of mobile phone area codes, please refer to https://en.wikipedia.org/wiki/List_of_country_calling_codes.	+86

SignInByAdPayloadDto

Name	Type	Required	Description	Sample value
password	string	Yes	User password, unencrypted by default. All GenAuth APIs transmit passwords securely via HTTPS, which can ensure security to a certain extent. If you need a higher level of security, we also support RSA256 and national secret SM2 password encryption methods. See the optional parameter options.passwordEncryptType for details.	passw0rd
sAMAccountName	string	Yes	sAMAccountName of the account in the Windows AD user directory	test

SignInByLdapPayloadDto

Name	Type	Is it required?	Description	Sample value
password	string	Yes	User password, unencrypted by default. All GenAuth APIs authenticate passwords via HTTPS.If you need a higher level of security, we also support RSA256 and the national secret SM2 password encryption method. For details, see the optional parameter options.passwordEncryptType.	passw0rd
sAMAccountName	string	yes	sAMAccountName of the account in the LDAP AD user directory	114114

SignInOptionsDto

| Name | Type | Required | Description | Sample value | | ------------------- | ------- | -------------------------------------- | ---------------------------- ... If you need to obtain the mobile phone number and email, you need to include phone email; if you need refresh_token, you need to include offline_access. Please separate multiple scopes with spaces. The decoded content of id_token will contain fields related to the user information corresponding to these scopes.
- openid: Must be included.
- profile: Returns birthdate, family_name, gender, given_name, locale, middle_name, name, nickname, picture, preferred_username, profile, updated_at, website, zoneinfo fields.
- username: Returns username.
- email: Returns email, email_verified.
- phone: Returns phone_number, phone_number_verified.
- offline_access: If this parameter exists, the token interface will return the refresh_token field.
- roles: Returns the user's role list.
- external_id: User ID of the original system.
- extended_fields: Returns the extended field information of the user, the content is an object, the key is the extended field name, the value is the extended field value.
- tenant_id: Returns the tenant ID of the user.
| openid profile | | clientIp | string | No | The real IP address of the client. By default, GenAuth will identify the IP address of the request source as the IP address of the user's login. If you call this interface in the backend server, you need to set this IP to the user's real request IP. | 192.168.0.1 | | context | object | No | Additional request context, which will be passed to the context object of Pipeline before and after authentication. Learn how to get additional context passed into the Pipeline's context parameter.| {"source":"utm"} | | tenantId | string | No | Tenant ID | 625783d629f2bd1f5ddddd98c | | customData | object | No | To set additional user custom data, you need to configure custom data in the GenAuth console first. | {"school":"pku","age":"20"} | | autoRegister | boolean | No | Whether to enable automatic registration. If set to true, an account will be automatically created for the user if it does not exist. Note: This parameter is only valid for the specified username and password, email password, and mobile phone number password. This parameter cannot be set for general account passwords. | | | captchaCode | string | No | Captcha graphic verification code, case-insensitive. When the security policy is set to verification code and the limit of failed logins is triggered, you will need to fill in a graphic verification code the next time you log in. | a8nz | | passwordEncryptType | string | No | Password encryption type, supports encryption using RSA256 and the national secret SM2 algorithm. The default is none, no encryption.
- none: Do not encrypt the password, use plain text for transmission.
- rsa: Use the RSA256 algorithm to encrypt the password. You need to use the RSA public key of the GenAuth service for encryption. Please read the introduction section to learn how to obtain the RSA256 public key of the GenAuth service.
- sm2: Use the national secret SM2 algorithm to encrypt the password. You need to use the SM2 public key of the GenAuth service for encryption. Please read the introduction section to learn how to obtain the SM2 public key of the GenAuth service.
| sm2 |

LoginTokenResponseDataDto

Name	Type	Is it required?	Description	Sample value
scope	string	no	Scope corresponding to access_token	openid profile
access_token	string	no	API call credentials, authorized to access resource API within a limited time	eyJhbGciOiJSxxxxx
id_token	string	no	User's identity credentials, which will contain user information after parsing	eyJhbGxxxx
refresh_token	string	no	refresh_token is used to obtain a new AccessToken	WPsGJbvpBjqXz6IJIr1UHKyrdVF
token_type	string	yes	Token type	bearer
expire_in	number	yes	Expiration time in seconds	7200