POST /auth/login

Login with username, email, or phone number plus password. Supports progressive delay anti-brute force, CAPTCHA human verification, and risk assessment. Returns JWT token on success. Reference: NIST SP 800-63B §5.1.1.2, OWASP ASVS V2.1.

Request Body

Schema: dto.LoginRequest

Field	Type	Required	Example	Constraints	Description
identity	string	Yes			Username/Email/Phone
password	string	Yes			Password or hash/ciphertext (depends on password_transmission)
captcha_challenge_id	string	No			CAPTCHA challenge ID
captcha_provider	string	No			CAPTCHA provider (pow/turnstile)
captcha_token	string	No			CAPTCHA verification token (PoW/Turnstile)
client_nonce	string	No			Hash mode: client random nonce
client_pub_key	string	No			Symmetric mode: client ECDH ephemeral public key
key_exchange_id	string	No			Symmetric mode: ECDH key exchange ID
key_id	string	No			Asymmetric mode: server public key ID
password_transmission	string	No			plain|hash|symmetric|asymmetric
tenant_id	string	No			Tenant ID

Responses

Status	Description	Schema
200	Login successful, returning access token and refresh token	dto.LoginResponse
400	Invalid request parameters or incorrect credentials	gitee_com_linmes_authms_base_dto.SimpleResponse
500	Internal server error	gitee_com_linmes_authms_base_dto.SimpleResponse

Referenced Schemas

dto.LoginResponse

User login result

Field	Type	Required	Example	Constraints	Description
access_token	string	No	eyJhbGciOi...		Access token
challenge_token	string	No	chg_abc123...		MFA challenge token (short-lived, requires MFA verification)
expires_in	integer	No	1800		Expiration time
mfa_check_reason	string	No	new_device		MFA trigger reason description
must_change_password	boolean	No	False		Password must be changed
password_expires_in	integer	No	30		Days until password expires
password_warning	string	No	expiring		Password warning: expiring/expired_grace/expired
refresh_token	string	No	eyJhbGciOi...		Refresh token
required_mfa_methods	array of string	No			List of recommended MFA methods
requires_mfa	boolean	No	False		Adaptive MFA: additional MFA verification required
risk_assessment	object	No			Risk assessment
risk_level	string	No	low		Risk level: low/medium/high
token_type	string	No	Bearer		Token type
user	object	No			User info
user_id	string	No			User ID (redundant with User.ID for flat access)

dto.RiskAssessmentInfo

Field	Type	Required	Example	Constraints	Description
level	string	No
recommended_mfa_methods	array of string	No
require_mfa	boolean	No
score	integer	No

dto.UserInfo

User basic information

Field	Type	Required	Example	Constraints	Description
created_at	string	No	2026-01-15T10:30:00Z		Account creation time
email	string	No	john@example.com		Email
id	string	No	usr_abc123		User ID
must_change_password	boolean	No	False		Password must be changed
password_expires_in	integer	No	30		Days until password expires
password_warning	string	No	expiring		Password warning: expiring/expired_grace/expired
phone	string	No	13800138000		Phone
status	string	No	active		Status
username	string	No	john.doe		Username

gitee_com_linmes_authms_base_dto.SimpleResponse

Field	Type	Required	Example	Constraints	Description
code	integer	No
message	string	No
timestamp	string	No