cTrader Open API authentication process is designed based on OAuth 2.0.
The OAuth 2.0 authorization framework allows the third-party applications obtaining limited access to the service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the service, or by allowing the third-party application to obtain access on its own behalf.
The communication with the resource (e.i. trading account) owner looks as follows:
A trading account owner decides to start using your service by clicking some action button on your site.
The service generates a request to the Open API 2.0, redirecting the trader to cTrader ID service.
Trader logs in using his personal cTrader profile and allows permissions.
After that, the trader is redirected back to the service side with an authentication code which can be exchanged with an access token. The access token allows the service to perform operations with the trading account on behalf of the trader.
To experiment with the API authorization process you can use the playground option of your API application.
For accessing playground go to your Open API applications page, click on an application playground button:
Playground allows you to easily get an access token for one of your Open API applications.
once you are in your application playground page click on "Get Token" button:
After clicking on the button, you will be redirected to the account authentication page.
Log in using your cTrader ID, select some of your connected trading accounts for authorization and click on the "Allow Access" button.
You will be redirected back to playground page, but this time it will show you the access token data:
You can use that access token for sending/receiving messages to the API.
In order to obtain access to a trading account’s information and trade on its behalf, you should have an authentication token for each cTrader ID that uses your application.
cTrader gives each user a cTrader ID, and all of the trading accounts of that user from all brokers will be linked to that cTrader ID, and Open API uses cTrader ID to give you access to some or all of a user linked trading accounts, based on the user given permission.
First you must have an active Open API application.
Your API application status on your applications page must be "Active".
Then add a redirect URL to your API application.
The API will redirect the user to this URL after account authorization and it will pass the access code as a URL parameter.
Adding Redirect URI¶
Open your applications page, and click on your application "Edit" button:
In your application edit page, scroll down and find the "Redirect URIs" section:
As you can see your application can have as many redirect URI as it needs, and you can add a new one by clicking on the "Add Redirect URI" button.
The first redirect URI is for the playground. You can't remove or change it, and you must not use it for your applications.
Once you add the "Redirect URIs" click on "Save" and that's it.
Getting Authorization Code¶
Now you are ready to get an authentication code from a cTrader user, URI:
You have to replace the "your_app_client_id" with your Open API application client ID and "redirect_uri" with one of your application redirect URIs.
After you fill the authentication URI with your app credentials, open it and you will see the cTrader ID login page.
Login to a cTrader ID with some trading account.
After logging in you will see the cTrader ID trading accounts list, with a check box for authorizing access to that trading account.
Click on "Allow Access" button.
You will be redirected to your application redirect URI and the Authorization Code will be appended as a parameter to the redirect URI:
Get the authorization code from redirect URI and generate an access token from it.
The authorization code has a one minute expiry time, you must exchange it with an access token as soon as possible otherwise it will be invalidated.
Getting an Access Token¶
To exchange an authorization code with an access token you have to send the authorization code to this URI:
The response will have this properties:
- accessToken: The access token string that you will use for authentication on API messages
- refreshToken: The refresh token string that you will use for updating your access token in case it expired
- expiresIn: The expiry time interval of access token in seconds
- tokenType: The token type, REST standard which is usually Bearer
- errorCode: In case of any error you will find the code here
- description: The string description of error
1 2 3 4 5 6 7 8 9 10
The above token will expire after 2628000 seconds from issuing time.
The expiry is in seconds, starting from the time you got the token.
Once your token expires you can use the refresh token to get a new access token.
Refreshing Access Token¶
The access tokens have expiry time, once a token reaches its expiry you will not be able to use that token anymore, and you have to refresh the expired token.
The refresh token never expires and each access token has a refresh token.
To refresh your access token you have to send the refresh token to:
It will give you back a new generated token with a new refresh token, now you can use this new token data instead of the old one which is invalidated.
Instead of the HTTP request method you can use the ProtoOARefreshTokenReq API message to refresh your expired token via Protocol Buffers and it will return a ProtoOARefreshTokenRes message which will have the new token data.
If you are not aware of what cTrader ID is, why you need this and how it works, please check the corresponding section below. Because you have to have it to play with OAuth services.
If you are not aware of OAuth technology, please check the OAuth standard reference RFC6749: The OAuth 2.0 Authorization Framework.