A.2 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/.
Security Considerations
Token Management
- Store tokens securely in backend systems
- Never expose tokens in client-side code
- Implement token rotation mechanisms where applicable
- Monitor token usage for anomalous patterns
Connection Security
- All requests must use HTTPS protocol
- Implement proper SSL/TLS configurations
- Use secure key storage for manager credentials
- Regularly rotate manager passwords
Error Handling
- Implement proper error handling for authentication failures
- Log authentication attempts for security monitoring
- Provide meaningful error messages for debugging
- Implement rate limiting for authentication endpoints
This authentication framework ensures secure bidirectional communication between broker systems and cTrader backend, forming the foundation for all SSO (OAuth) operations.