App and account authentication¶

The cTrader Open API authentication process is based on the OAuth 2.0 standard.

This framework allows third-party applications to attain limited access to a service either on behalf of the resource owner, by orchestrating an approval interaction between the resource owner and the service, or by allowing a third-party application to attain access on its own behalf.

Authentication flow¶

As per the OAuth 2.0 standard, account authentication requires both an authorisation code and an access token.

Typically, the process of someone new starting to use your application for the first time looks as follows:

1. A user with a certain cTID accesses your application wherever it is deployed; the user interacts with an action button or equivalent.

2. The application uses an embedded browser (or any other suitable means) to redirect the user to a specific URI where they will give the app the necessary permissions.

3. The user is transferred to a predefined redirect URL. This URL contains the access token as the value of the code query parameter.

4. The user is transferred back to the app either of their own accord or automatically. The app is informed of the value of the code parameter.

5. The app sends a request for exchanging the authorization code with an access token to a specific endpoint.

6. The app receives a response containing the access token as the value of the accessToken key.

7. The app sends the ProtoOAApplicationAuthReq message containing the clientId and clientSecret fields.

8. The app sends the ProtoOAGetAccountListByAccessTokenReq message containing the accessToken field. The response (ProtoOAGetAccountListByAccessTokenRes) contains the repeated ctidTraderAccountId field.

9. After receiving a response, the app sends the ProtoOAAccountAuthReq message containing the ctidTraderAccountId and accessToken fields.

Afterwards, the user should be authenticated under the account the ctidTraderAccountId of which matches the ctidTraderAccountId provided during step 8.

The diagram below explains how the basic authentication flow works from the perspective of your Open API application.

graph TB
  A([Redirect the user to a <br/> specific URI]) ==> B([Receive the authorisation <br/> code]);
  B ==> C([Send a request for attaining <br/> an access code]);
  C ==> D([Send the <br/> ProOAApplicationAuthReq <br/> message]);
  D ==> E([Send the <br/> ProtoOAAccountAuthReq <br/> message]);

In the sub-sections below, we explain the key steps of the authentication flow in detail.

Add a redirect URI¶

As shown previously, your app needs to attain an authorisation code after a user is sent to a certain redirect URI. This URI will include the authorisation code as the value of the code query parameter.

To add a new redirect URI, do the following:

1. Open the Applications page in the Open API portal.

2. Select the Edit button in the row with the application to which you would like to add a redirect URL.

3. In the newly appeared screen, scroll down to the Redirect URIs section.

4. Add a redirect URL in an available empty text input field. If no available fields are shown, select the Add redirect URI button.

5. Select the Save button at the bottom of the page to apply your changes.

Attain the authorisation code¶

To receive an authorisation code for a specific cTID, your app will need to send a user to the following URI.

https://id.ctrader.com/my/settings/openapi/grantingaccess/?client_id={clientId}&redirect_uri={your_redirectURI}&scope={scope}&product=web

This URI has the following query parameters.

To view your client_id, go to the Applications page and select the View button in the Credentials column.

After a user is sent to the URI above (and as long as both parameters are valid), they should see a login/signup screen prompting them to authorise under their cTID. Following that, a user will be shown a dialog where they will be able to permit the application to gain access to one or more accounts linked to their cTID.

When the user selects the Allow access button, they will be redirected to the redirect_uri you had specified originally. As shown in the below example, the authorization code will be added to this URI as a query parameter.

https://my-redirect-uri.com/?code=123ASDASffdg_as234_GCllkoq14adRB7_tvN

At this point, your application would need to access and store the value of the code parameter. It must be quickly exchanged with an access token before the authorisation code expires.

Attain an access token¶

To get an access token, perform the following REST API call.

This request includes the following query parameters.

The request example can be found below.

curl -X GET 'https://openapi.ctrader.com/apps/token?grant_type=authorization_code&code=0ssdgds98as9_QSF56FVC_22dfdf&redirect_uri=https://spotware.com&client_id=5430012&client_secret=012sds23dlkjQsd' -H 'Accept: application/json' -H 'Content-Type: application/json'

To view your client_secret, return to the Applications page and select the View button in the Credentials column.

Upon a successful request, you should receive a response with the following keys.

For an example of a successful response, see the snippet below.

{
    "accessToken":"mos8Bw3D4EG0fRPd4Eqq0JxaFT4zjd8e4YijNezh_ag",
    "tokenType":"bearer",
    "expiresIn":2628000,
    "refreshToken":"VCuafFhy81AFZjsWkbuEzdOhhRj5YTWz8fWUwHam7KM",
    "errorCode":null,
    "description":null,
}

Send the required ProtoBuf messages¶

After receiving a valid access code, your application will need to send the ProtoOAApplicationAuthReq, ProtoOAGetAccountListByAccessTokenReq and ProtoOAAccountAuthReq messages. This can be done as follows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

private static RepeatedField<ProtoOACtidTraderAccount> _ctidTraderAccounts;

List<IDisposable> _disposables = new();
_disposables.Add(_client.OfType<ProtoOAGetAccountListByAccessTokenRes>().Subscribe(OnAccountIdReceived));

private static void OnAccountIdReceived(ProtoOAGetAccountListByAccessTokenRes response)
{

    Console.WriteLine($"\nMessage Received:\n{response}");

    _ctidTraderAccounts = response.CtidTraderAccount;

    var accountAuthReq = new ProtoOAAccountAuthReq
    {
        CtidTraderAccountId = (long)_ctidTraderAccounts[0].CtidTraderAccountId,
        AccessToken = _token.AccessToken,
    };

    _client.SendMessage(accountAuthReq);

}

var _client = new OpenClient(host, ApiInfo.Port, TimeSpan.FromSeconds(10), useWebSocket: false);
var applicationAuthReq = new ProtoOAApplicationAuthReq
{
    ClientId = {your_client_id}, // Add your client ID here
    ClientSecret = {your_app_secret}, // Add your app secret here
};
await _client.SendMessage(applicationAuthReq);
await Task.Delay(5000);
var getAccountListByAccessToken = new ProtoOAGetAccountListByAccessTokenReq 
{
    AccessToken = {access_token} // Add your access token here
}
var accountAuthReq = new ProtoOAAccountAuthReq 
{
    ctidTraderAccountId = {account_id}, // Add the ctidTraderAccountId of the account you want to authorize here
    AccessToken = {access_token} // Add your access token here
};
await _client.SendMessage(accountAuthReq);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

currentAccountId = None
client = Client(EndPoints.PROTOBUF_LIVE_HOST if hostType.lower() == "live" else EndPoints.PROTOBUF_DEMO_HOST, EndPoints.PROTOBUF_PORT, TcpProtocol)

def connected(client): # Callback for client connection
    print("\nConnected")
    request = ProtoOAApplicationAuthReq()
    request.clientId = appClientId
    request.clientSecret = appClientSecret
    deferred = client.send(request)



def disconnected(client, reason): # Callback for client disconnection
    print("\nDisconnected: ", reason)

def onMessageReceived(client, message): # Callback for receiving all messages
    global currentAccountId
    if message.payloadType in [ProtoOASubscribeSpotsRes().payloadType, ProtoOAAccountLogoutRes().payloadType, ProtoHeartbeatEvent().payloadType]:
        return
    elif message.payloadType == ProtoOAApplicationAuthRes().payloadType:
        print("API Application authorized\n")
        if currentAccountId is not None:
            sendProtoOAAccountAuthReq()
            return
        accountListReq = ProtoOAGetAccountListByAccessTokenReq()
        accountListReq.accessToken = accessToken
        deferred = client.send(accountListReq)
    elif message.payloadType == ProtoOAGetAccountListByAccessTokenRes().payloadType:
        protoOAGetAccountListByAccessTokenRes = Protobuf.extract(message)
        currentAccountId = int(protoOAGetAccountListByAccessTokenRes.ctidTraderAccount[0].ctidTraderAccountId)
        accountAuthReq = ProtoOAAccountAuthReq()
        accountAuthReq.ctidTraderAccountId = currentAccountId
        accountAuthReq.accessToken = accessToken
        deferred = client.send(accountAuthReq)
    elif message.payloadType == ProtoOAAccountAuthRes().payloadType:
        protoOAAccountAuthRes = Protobuf.extract(message)
        print(f"Account {protoOAAccountAuthRes.ctidTraderAccountId} has been authorized\n")
        print("This acccount will be used for all future requests\n")
    else:
        print("Message received: \n", Protobuf.extract(message))
    reactor.callLater(3, callable=executeUserCommand)

def onError(failure): # Call back for errors
    print("Message Error: ", failure)
    reactor.callLater(3, callable=executeUserCommand)

Refresh the access token¶

After an access token expires, you will have to renew it using the refreshToken you received earlier. You can perform this action via two different methods.

Send an HTTP request¶

To attain a new access token (and, subsequently, a new refresh token), you can perform the same HTTP request covered above. As shown in the below example, you would have to set the grant_type query parameter to refresh_token.

curl -X POST 'https://openapi.ctrader.com/apps/token?grant_type=refresh_token&refresh_token=asdXCVCVAS_218kjashf_asdasd2ASD_223x&client_id=5430012&client_secret=012sds23dlkjQsd' -H 'Accept: application/json' -H 'Content-Type: application/json'

You will receive a response containing the new values of the accessToken and refreshToken keys. You can safely use these new values while the old values of the same keys are automatically invalidated.

Send a Protobuf message¶

Alternatively, you can send the ProtoOARefreshTokenReq and receive the ProtoOARefreshTokenRes message containing new valid tokens.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

_disposables.Add(_client.OfType<ProtoOARefreshTokenRes>().Subscribe(OnRefreshTokenResponse));
private static void OnRefreshTokenResponse(ProtoOARefreshTokenRes response) 
{
    _token = new Token 
    {
        AccessToken = response.AccessToken,
        RefreshToken = response.RefreshToken,
        ExpiresIn = DateTimeOffset.FromUnixTimeMilliseconds(response.ExpiresIn),
        TokenType = response.TokenType,
    }
}
var refreshTokenReq = new ProtoOARefreshTokenReq
    {
        refreshToken = {your_refresh_token}, // Add your refresh token here
    };
await _client.SendMessage(applicationAuthReq);

1

newToken = auth.refreshToken("refresh_Token")

Use the Playground¶

The Playground provides a quick means for attaining an access token for your own cTID, allowing you to quickly and easily develop and test your app before distributing it among its target audience.

To access the Playground, go to the Applications page and select the Playground button. In the newly appeared window, select the scope of the application and click the Get token button.

Afterwards, you should see the following page.

You can use the access token and the refresh token for sending messages to the API while authenticated under your own cTID.