5. URLs and User Flows
5.1. Key Rules
Section 5 outlines the key SSO (OAuth) and InApp flows. Along with a process diagram, each flow is provided with a detailed description of its stages. When applicable, the process diagrams also list the relevant API calls in brackets.
All user flows described in this section are fully compliant with the OAuth 2 standard (RFC8252) to maximise security and improve UX.
5.2. URLs and Their Parameters
The SSO (OAuth) flows require the existence of a custom user creation/authorisation (login/signup) screen. Additionally, the user creation flow (5.3.) requires a trading account creation screen.
The front-end component of these screens is designed and implemented by the broker. Please note that the screens should be designed replace the default cTrader login/signup (and account creation) pages. The screens must not include any browser-related controls.
When performing various InApp actions, users are also sent to pre-defined URLs relevant to a particular InApp action. For example, clicking on the button for making a deposit should provide users with a custom deposit options screen. Similarly to the above provisions, these screens must be created by brokers and should be consistent with other elements of the UI. However, users must be able to close these screens by clicking on a 'Back' button, an 'X' button, or something similar.
The URLs hosting your SSO (OAuth) screens can accept several mandatory and optional query parameters.
Parameters
| Parameter | Screen(s) | Required? | Data Type | Description |
|---|---|---|---|---|
lang | All screens | No | string | The language of the device OS. This parameter allows for displaying forms and screens in different languages. The parameter takes Alpha-2 (ISO 369-2) codes as values. |
source | All screens | No | string | The type of the application accessing the screen. Applicable values include "Web", "Android", "iOS", "MacOS", and "Desktop". Brokers can also use this parameter to adjust the screen design for various devices. |
theme | All screens | No | string | The preferred colour scheme of the app (can be either "light" or "dark"). This parameter is needed for the broker to establish a consistent design and ensure that the screens appear native to the trading application. |
firstLogin | Login/signup | No | boolean | A flag determining whether this is the user's first login attempt on the current device. As Spotware only supports a single URL for the login/signup screen, this parameter is needed for the broker's CRM system to correctly recognise whether it needs to open its user creation page or the login form. The value of true denotes the user's first per-device login, and vice versa. |
partnerId | Login/signup | No | string | The email assigned as a partner identifier to a specific user or an account. |
token | InApp actions | Yes | string | The OT token required for authorisation. |
account | InApp actions | Yes (only for deposits/withdrawals); No (in other cases) | integer | The number of a specific trading account linked to the user. |
Note that cTrader Mobile also supports UTM parameters as query parameters for all broker SSO (OAuth) screens.
| Parameter | Screen(s) | Required? | Data Type | Description |
|---|---|---|---|---|
utm_source | All screens | No | string | The source channel from which the user is transferred to an OAuth screen. |
utm_medium | All screens | No | string | The type of content that encouraged the user to click on a link and be transferred to an SSO (OAuth) screen. |
utm_campaign | All screens | No | string | The name of the marketing campaign as a result of which the user is transferred to an SSO (OAuth) screen. |
utm_term | All screens | No | string | The keyword that the user engages with and, as a result, is transferred to an SSO (OAuth) screen. |
utm_gclid | All screens | No | string | The Google Click identifier assigned to the user being transferred to an SSO (OAuth) screen. |
5.3. User Creation Flow
This user flow covers actions necessary for first-time user creation. To learn more, click here.
5.4. User Authorization With a Password Flow
This flow covers the cases in which a user is already registered in the cTrader backend and in the broker's CRM system. To learn more, click here.
5.5. Automatic Re-Login Flow
This flow applies to cases in which a user has been previously authorized using the same application and the same device as in their current session; additionally, the 'Keep Me Logged In' (or a similarly named) option is selected. To learn more, proceed here.
5.6. Embedded cTrader Web Flow
This flow describes the cases in which users that have registered their first account in the broker's CRM want to open embedded cTrader Web. To learn more, click here.
5.7. InApp Actions Flow
This flow outlines the general sequence of event that occur when a user wants to perform an InApp action. To learn more, click here.
5.8. Trader Attribution Flows
These flows showcase how trader-partner attribution works when our SSO (OAuth) solution is deployed. To learn more, click here.