To initiate work with the WebAPI after establishing a connection, authentication is required. There are two types of logon messages:
•Single-step: user_session_2.Logon
•Multi-step: user_session_2.LogonRoutineClient
The simplest available authentication method, requiring a single roundtrip.
Example with Login and Password
Client Message:
{
"logon": {
"user_name": "user name",
"password": "***",
"private_label": "company",
"client_app_id": "company app",
"client_version": "1.0",
"protocol_version_major": 2,
"protocol_version_minor": 240
}
}
•client_app_id and private_label are provided by CQG for your application. Note: real values are generated when your app moves to the production environment after passing the conformance test. Before that, your login is most likely configured to use private label WebApiTest and client app ID WebApiTest.
•protocol_version_major and protocol_version_minor specify the supported protocol version. The client version shouldn’t be greater than the server version, as this may lead to malformed messages or unexpected behavior. Clients with older versions are supported until an explicit notice; the WebAPI server provides backward-compatible behavior for them.
Server Response:
{
"logon_result": {
"result_code": 0,
"base_time": "2013-04-03T14:23:20",
"session_token": "session
identifier",
"protocol_version_major": 2,
"protocol_version_minor": 250,
"user_id": 12345,
"server_time": 5432100000
}
}
•result_code: 0 indicates a successful logon.
•base_time is used for *_time field calculations.
•session_token is the identifier for restoring or joining a session.
•server_time is the time the server sent the message. See time conversion for details.
Logon with an access token is an authentication method used as part of OAuth/SSO. The access token must be sent in the logon message instead of user_name and password.
Additional setup is required to enable this. Contact customer support for details on obtaining an access token.
This authentication process allows user interaction and encodes passwords securely. See user_session_2.LogonRoutineClient and user_session_2.LogonRoutineServer.
1. Client initiates negotiation by sending LogonRoutineClient.logon_init.
2. Server requests one or more LogonRoutineServer.password_request messages.
3. Client responds with LogonRoutineClient.password_response.
4. Server may request agreement acceptance (LogonRoutineServer.trader_agreement_url).
5. Client responds with LogonRoutineClient.trader_agreement_accepted = true if accepted, or false / abort_logon otherwise.
6. Server sends LogonRoutineServer.logon_result as the final step.
The client may terminate the process by sending LogonRoutineClient.abort_logon in response to any server LogonRoutineServer.password_request or LogonRoutineServer.trader_agreement_url requests.
Regulatory requirements may mandate additional client identifiers in the logon message.
Client Message:
{
"logon or logon_init": {
...
"fingerprint": "stable client app
id",
"operating_system": "Linux",
"browser": "Chrome",
"device_model": "PC"
}
}
If the logon result contains an inactivity_timeout field, the client application should track user activity and terminate the session after the timeout period.
Server Response:
{
"logon_result": {
...
"inactivity_timeout": 60
}
}
This means the session should be closed if there is no interaction for 60 minutes.
To change the user password, use user_session_2.PasswordChange or user_session_2.PasswordChangeRoutineClient.
The client must be logged in or receive LogonResult.result_code = RESULT_CODE_PASSWORD_EXPIRED.
Client Message:
{
"password_change": {
"old_password": "old ***",
"new_password": "new ***"
}
}
Server Response:
{
"password_change_result": [{
"result_code": 0
}]
}
Clients can restore or join an existing session within a short time without re-authenticating. An IP check is enforced, so the request can only be made from the same IP address. This is controlled by the Logon.session_settings field:
•SESSION_SETTING_ALLOW_SESSION_RESTORE: Allows session restoration after a disconnect.
•SESSION_SETTING_ALLOW_SESSION_JOIN: Allows multiple concurrent connections.
If these settings are enabled, after establishing a new connection, send user_session_2.RestoreOrJoinSession:
Client Message:
{
"restore_or_join_session": {
"session_token": "session
identifier",
"private_label": "company",
"client_app_id": "company app",
"protocol_version_major": 2,
"protocol_version_minor": 240
}
}
Server Response:
{
"restore_or_join_session_result": {
"result_code": 0,
"base_time": "2013-04-03T14:23:20",
"server_time": 5432100000
}
}
Other active connections will receive a notification:
Server Notification:
{
"concurrent_connection_join_results": [{
"is_same_app_type": true
}]
}
Note: After restoring or joining, the client must reinitialize all subscriptions.
To finish the WebAPI session, send user_session_2.Logoff. However, note that unconfirmed messages (e.g., order request) may be ignored after logoff.
Client Message:
{
"logoff": {}
}
Server Response:
{
"logged_off": {
"logoff_reason": 1
}
}
The server may also send a LoggedOff message unexpectedly due to events like concurrent login or network issues.
Some accounts require an additional account-level logon before accessing trading information or executing orders.
The client can identify such accounts by the presence of account_connection_status in Account.
Similar messages are used for account-level authentication:
•Logon: account_authorization_2.AccountLogonRoutineClient
•Logoff: account_authorization_2.AccountLogoff
•Password Change: account_authorization_2.AccountPasswordChange or account_authorization_2.AccountPasswordChangeRoutineClient