API Calls

All API calls here are made by the broker's backend to the cTrader backend.

Register a User

HTTP Method	URL
`POST`	`/ctid/create`

Creates a new user entity.

Parameters

No parameters.

Request Body

Key	Required?	Data Type	Description
`brokerName`	No	string	A unique name denoting a specific broker (including White Labels).
`email`	Yes	string	The email address assigned to the new user.
`preferredLanguage`	No	string	An Alpha-2 code denoting the preferred language of the new user.

Output

info

Note that there are two possible outputs depending on whether you specify a unique email in the request body (an email that is not used by any of the users registered on your server). If email is unique, the response will include all parameters from the below table. If the specified email is already assigned to an existing user, the output will only include the userId parameter.

Key	Data Type	Description
`userId`	integer	The unique identifier of the user entity.
`nickname`	string	The nickname of the user entity. By default, `nickname=ctid{userId}`.
`email`	string	The email assigned to the user entity.
`preferredLanguage`	string	An Alpha-2 code denoting the preferred language of the user entity.
`utcCreateTimestamp`	integer	The epoch unix timestamp of the creation of the user entity.
`status`	enum	The status of the new user entity. Possible values: - `"CTID_NEW"`. The default status for any new user. - `"CTID_ACTIVE"`. The status denoting an existing active user who has confirmed their email address in the cTrader ecosystem. Note that only users with `"CTID_ACTIVE"` as their `status` receive trading notifications in their email inbox. - `"CTID_DELETED"`. The status denoting a deleted user entity. Note that receiving `"CTID_ACTIVE"` or `"CTID_DELETED"` in the response body would constitute unexpected behavior.

For a JSON schema of the output, click here.

Request Example

curl -X POST 'https://HOST:PORT/cid/ctid/create?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"brokerName": "BESTBROKER", "email": "president@bestbroker.com", "preferredLanguage": "EN"}' 

Response Examples

If a Unique `email` Is Specified
If an Existing `email` Is Specified

{
  "userId": 10333,
  "nickname": "ctid10333",
  "email": "president@bestbroker.com",
  "utcCreateTimestamp": 1679898064783,
  "preferredLanguage": "en",
  "status": "CTID_NEW"
}

{
  "userId": 10333
}

Expected Status Code

200

Get One-Time Code for User

Method	URL
`POST`	`/v1/users/{userId}/authcode`

Generates the one-time code required for the SSO.

Parameters

Parameter	Parameter Type	Required?	Data Type	Description
`userId`	path	Yes	integer	The unique ID of the user.

Headers

Header	Description	Required?	Notes
Authentication header	Authentication token for WebServices API. E.g. `1a1fc081-f8d9-81a4-6b43-f9e42ed0c1d7`	Yes	The manager whose token is used to send the request must have permission to authenticate users.

Request Body

Key	Required?	Data Type	Description
`brokerNames`	Yes	string array	Broker names (white labels) for which access is requested.

Output

Key	Data Type	Description
`сode`	string	One-time code which can be exchanged for an authentication token. Valid for 60 seconds.

Request Example

curl -X POST 'https://HOST:PORT/cid/v1/users/{userId}/authcode' 'Authorization: Bearer 7f1fc081-f8d9-81a4-4b43-f9e42ed0c7d8' 'Content-Type: application/json' 'Accept: application/json' '{"brokerNames": ["BESTBROKER"]}' 

Expected Response Status Code

200

Response Example

{
  "сode": "3b8aa6ff-ec5b-460e-a149-346e7ec2b9ff"
}

Register a User​

Get One-Time Code for User​

Register a User

Get One-Time Code for User