LOGIN API

This API is used to authenticate users by validating their login credentials.

Upon successful full authentication, the API returns:

• access_token — Must be included in the Authorization header of all subsequent API requests to authorize the user's session.
• broadcast_access_token — Required to establish a connection with the market feed endpoint via the broadCastSocket URL provided in the response. Refer to the Price Feed API for detailed usage. The response also includes essential trading information such as allowed exchanges, supported product types, MPIN/fingerprint/TOTP registration status, and GTD configuration.

This API is a prerequisite for accessing all authenticated endpoints in the system.

🗝️Login Types and Second-Factor Authentication

The Login API supports a two-step authentication flow. On the first call, pass second_auth_type: "REGISTER" to validate the password and receive a register_token. Then use that token in a second call with login_type: "TOKEN" and the appropriate second-factor credential.

login_type	password Field Value	second_auth_type	second_auth Value
PASSWORD	User's password	REGISTER	Not required (leave empty)
TOKEN	register_token from Step 1	OTP / TOTP / FINGERPRINT	OTP value / TOTP value / Registered UDID
PASSWORD	User's password	OTP / TOTP / FINGERPRINT	OTP value / TOTP value / Registered UDID
MPIN	Registered MPIN	OTP / TOTP / FINGERPRINT	OTP value / TOTP value / Registered UDID
TP_TOKEN	SSO token (external auth)	Not required	Not required

📝 Two-Step Authentication Flow

Step 1 — First login call (get available 2FA methods):

• Set login_type: "PASSWORD", pass the user's password, and set second_auth_type: "REGISTER".
• The API validates the password and returns a register_token along with the available second-factor methods (ptnType) and registration flags (mpin_enabled, fingerprint_enabled, totp_enabled).

Step 2 — Second login call (complete authentication):

• Set login_type: "TOKEN", pass the register_token from Step 1 as the password field, and provide the chosen second-factor in second_auth_type and second_auth.
• On success, the API returns the full access_token and trading data.

🔑Header Parameters

Header	Type	Description	Example
Content-Type	string	Specifies the media type of the request payload	application/json
x-api-key	string	API key used to authorize the request	x-api-key

📑Request Body Parameters

Field	Type	Required	Descripiton	Example/Enum
user_id	string	Yes	User ID (UCC) Provided to the user	"UCC123456"
login_type	string	Optional	Specifies the login method. Determines which value is passed in the password field. Use TP_TOKEN when authentication is handled externally 9eg., via a Super APP)	Default: "PASSWORD" Enum : PASSWORD, MPIN, FINGERPRINT, TP_TOKEN
password	string	Yes	Password, MPIN, UDID or SSO Token depending on the login_type selected.	"mypassword123"
second_auth_type	string	Optional	Type of secondary authentication selected by the user.User REGISTER on first login to register a second-factor method.	Enum : OTP, TOTP, FINGERPRINT, REGISTER
second_auth	string	Optional	The credential value for the selected secondary authentication type (e.g., OTP, TOTP,UDID)	"123456"/"MyDeviceID"
api_key	string	Yes	API Key provided by Synapsewave for authenticating the client application	"xyz-api-key"
source	string	Yes	Indicates the platform from which the user is logging in	Enum : WEBAPI, MOBILEAPI
UDID	String	Optional	Unique Device ID of the user's device.	"device-12345-udid"
version	string	Optional	version number for the Android application	"2.1.0"
iosversion	string	Optional	Version number of the iOS application	"3.0.5"
build_version	string	Optional	Internal build version of the application	"build-45"
deviceinfo	object	Optional	Additional information about the user's device (e.g., OS, model, etc)	{"os" : "Android", "model" : "Pixel 6"}

📘DeviceInfo Object Fields

Field	Type	Description	Example/ENUM
UDID	string	The unique identifier for the device.	"123e4567-e89b-a456-426614174000"
DeviceModel	string	The model of the device from which the user has logged in.	"iPhone 12"
DeviceSerialNo	string	The serial number of the device used for log in.	SN1234567890
DeviceManufacturer	string	The manufacturer of the device used for login.	Apple
DevicePlatform	string	The platform of the device used for login	Web
DevicePlatformVer	string	The version of the platform (OS) on the device used for login.	14.4
Longitude	string	The longitude coordinate of the device's location when logging in.	77.5946
Latitude	string	The latitude coordinate of the device's location when logging in.	"12.9716"
AppName	string	The name of the application being used for login.	Wave 3.0
AppVersion	string	The version of the application used for login.	"1.2.3"
AppVersionCode	string	The version code of the application used for login.	"200000"
AppPackageName	string	The package name of the application used for login (Android only).	com.example.myapp
FCMRegKey	string	The Firebase Cloud Messaging (FCM) registration key for push notifications	"172.25.90.82:8100
IP	string	IP Address of the device used for login	"192.168.1.1"
SDKVersion	string	The version of the software development kit (SDK) used for the application.	"30"

🟢 Step 1 Response — second_auth_type: "REGISTER" — 200 OK

When second_auth_type is REGISTER, the API validates the password but does not return an access_token yet. Instead it returns a register_token and the user's available 2FA options for use in Step 2.

Content-Type: application/json

Field	Type	Description	Example
status	string	Status of the API call	"success"
code	string	Response code	"s-101"
message	string	Success message	"User logged in Successfully."
data	object	Step 1 response payload	Refer below

📦 Step 1 Data Object Fields

Field	Type	Description	Example
register_token	string	Temporary JWT token to be passed as the password field in the Step 2 login call	"eyJhbGciOiJIUzI1NiJ9..."
ptnType	string	Indicates the second-factor authentication methods available for this user	"TOTP_OPT", "OTP", "FINGERPRINT"
mpin_enabled	boolean	Whether the user has registered an MPIN	true / false
fingerprint_enabled	boolean	Whether the user has registered a fingerprint	true / false
totp_enabled	boolean	Whether the user has registered a TOTP authenticator	false / true

Note on ptnType: This field indicates which second-factor methods are configured for the user. Use it to determine which second_auth_type to present to the user in Step 2. For example, "TOTP_OPT" means TOTP is available as an option.

---

🟢 Step 2 Response — Full Authentication — 200 OK

When second_auth_type is OTP, TOTP, or FINGERPRINT, and authentication succeeds, the API returns the full session payload including the access_token.

Content-Type: application/json

Field	Type	Description	Example
status	string	Status of the API call	"success"
code	string	Response code	"s-101"
message	string	Success message	"User logged in Successfully."
data	object	Full session payload including token and user trading information	Refer to Data Object Fields

📦 Step 2 Data Object Fields

Field	Type	Description	Example
access_token	string	JWT session token; must be passed in the Authorization header of all subsequent API calls	"eyJhbGciOiJIUzI1NiJ9..."
user_id	string	User ID (UCC) of the authenticated user	"APITEST"
alias_id	string	Alias ID for the user; empty if not configured	""
user_name	string	Display name of the authenticated user	"API TEST"
login_time	string	Timestamp of the login (format: YYYY-Mon-DD HH:MM:SS)	"2023-Sep-20 14:15:02"
exchanges	string[]	List of exchange segments the user is permitted to trade on	["NSE_EQ", "NSE_FO", "BSE_EQ", "MCX_FO", "NSE_OTS", "MUTUAL_FUND", ...]
bcastExchanges	string[]	List of exchange segments the user can receive market feed data for	["NSE_EQ", "NSE_FO", "BSE_EQ", "MCX_FO", ...]
product_types	string[]	All product types permitted for the user across all exchanges	["INTRADAY", "DELIVERY", "COVER", "BRACKET", "MTF", "BTST"]
product_types_exchange	object	Product types permitted per exchange segment	{"NSE_EQ": ["INTRADAY", "DELIVERY", "MTF", ...], "NSE_FO": ["INTRADAY", "DELIVERY", ...]}
mpin_enabled	boolean	Whether the user has a registered MPIN	true / false
fingerprint_enabled	boolean	Whether the user has a registered fingerprint	false / true
totp_enabled	boolean	Whether the user has a registered TOTP authenticator	true / false
ptnType	string	Second-factor methods available for this user (same as Step 1 response)	"TOTP_OPT"
others	object	Additional configuration and socket connection details	Refer to Others Object Fields

📦 Others Object Fields

Field	Type	Description	Example
userCode	string	Internal user code assigned by the system	"NWSYF"
groupId	string	Group ID to which the user belongs	"HO"
groupCode	string	Group code of the user's group	"AAAAA"
newsCategories	string	Comma-separated news category IDs applicable to the user	"25051,25039,25038,..."
messageSocket	string	WebSocket endpoint for receiving interactive/system messages	"wss://socketio-uat.example.com:8443"
broadCastSocket	string	Primary WebSocket endpoint for receiving real-time market feed data; use with bcastExchanges	"wss://feed.example.com:4510"
secondBroadCastSocket	string[]	Fallback WebSocket endpoints for market feed data	["ws://feed2.example.com:4509"]
POA	string	Power of Attorney status of the user. "0" = POA user, "2" = Non-POA user	"0", "2"
nGTDDefault	integer	Default number of days for GTD (Good Till Day) orders	2
nGTDMaxDays	integer	Maximum number of days allowed for GTD orders	365
sGTDConfigDetails	string	GTD configuration string in the format "defaultDays|maxDays"	"2|9"
ocToken	string	OC (Order Confirmation) token used for internal OMS communication	"0x01C1DBD524FBF3C904..."
managerIP	string	Internal OMS manager host address	"Odindemo.63moons.com"
participantCode	string	Participant code for equity segment; empty if not applicable	""
dervParticipantCode	string	Participant code for derivatives segment; empty if not applicable	""
tslAllowed	string[]	List of exchange segments on which TSL (Trailing Stop Loss) orders are permitted	["NSE_EQ", "NSE_FO", "BSE_EQ", ...]
edisForMTF	boolean	Whether EDIS (Electronic Delivery Instruction Slip) is applicable for MTF positions	false / true
showJumpPriceBothLtpAndTriggerPrice	boolean	Whether to show jump price for both LTP and trigger price in the UI	false / true
CFT	string	Pipe-separated feature toggle configuration string indicating which platform features are enabled (1) or disabled (0) for this user	"HEATMAP|1$ALERT|1$IPO|1$..."
passExpDays	string	Human-readable message indicating when the user's password will expire	"Your password will expire in 845 Day(s)."
bAMOAllowedForUser	boolean	Whether the user is permitted to place AMO (After Market Orders)	true / false