Authentication of API calls
The SSO (OAuth) solution requires bidirectional authentication between broker systems and cTrader backend. This section details the token exchange mechanisms for secure API communication.
Authentication Overview
Broker to cTrader Authentication
The broker's backend is authenticated using manager credentials for API calls to the cTrader backend.
cTrader to Broker Authentication
The cTrader backend authenticates with the broker's CRM using a token exchange mechanism for user-facing operations.
Manager token authentication
Token Generation
For API calls made by the broker's backend to the cTrader backend, append an authentication token to each request by placing ?token={token} at the end of each request URL.
API Endpoint: Generate Manager's Token
| Method | URL |
|---|---|
POST | /webserv/managers/token |
Request Body
| Key | Required? | Data Type | Description |
|---|---|---|---|
hashedPassword | Yes | string | The MD5 of the manager's password. |
login | Yes | integer | The unique ID of the manager. |
Output
| Key | Data Type | Description |
|---|---|---|
webservToken | string | A long-term token authenticating the manager. |
Request Example
curl -X POST 'https://HOST:PORT/v2/webserv/managers/token' -H 'Accept:application/json' -H 'Content-Type: application/json' -d '{"hashedPassword": "0f94e246908667af85916300c57f74b6", "login": 2309}'
Expected Response Status Code
200
Response Example
{
"webservToken": "04d95575-c9af-42fba72e-2f0ce93f01d4"
}
Token Usage
- The manager token does not have an expiration period
- Must be included in all subsequent API calls to cTrader backend
- Token format:
?token={webservToken}appended to request URLs
CRM API token authentication
Token exchange process
The cTrader backend authenticates with the broker's CRM by exchanging a pre-generated password for a long-term authentication token.
API Endpoint: Authenticate cTrader Backend
| Method | URL |
|---|---|
POST | /oauth2/crmApiToken |
Request Body
| Key | Required? | Data Type | Description |
|---|---|---|---|
password | Yes | string | The password generated by the cTrader backend. |
Output
| Key | Data Type | Description |
|---|---|---|
crmApiToken | string | A non-repeatable token authenticating the cTrader backend. After it is issued, it is placed in the memory storage of the cTrader backend. |
Request Example
curl -X POST 'https://brokerCrmUrl.com/oauth2/crmApiToken' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"password": "af34mn0pphg2893nmaf26hmy"}'
Expected Response Status Code
200
Token Requirements
- Validity Period: Must be valid for at least one week
- Storage: Stored in cTrader backend memory after issuance
- Usage Format:
?crmApiToken={crmApiToken}appended to request URLs
Content type specifications
The API calls accept different content types based on endpoint patterns:
| Endpoint Starting With | Accepted Content Types |
|---|---|
/ctid/ or /oauth2/ | Text/JSON only |
/webserv/ | Text/JSON and text/XML |
URL Base Patterns
cTrader Backend URLs
The endpoints are relative to the following URLs. The unique value of https://HOST:PORT is provided by Spotware Systems to each individual broker.
| Endpoint Starting With | Relative To |
|---|---|
/ctid/ or /oauth2/ | https://HOST:PORT/cid |
/webserv/ | https://HOST:PORT/v2 |
Broker CRM URLs
All API calls received by your client area/CRM must be available at endpoints relative to one consistent URL. Avoid establishing some endpoints at broker.com while hosting others at my.broker.com. These endpoints are referenced as https://brokerCrmUrl.com/.