Open Authentication

Spotware 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 resource (e.g. trading account) owner looks as follows:

  1. A trading account owner decides to start using your service by clicking some action button on your site.

  2. The service generates a request to the Open API 2.0, redirecting the trader to Spotware side.

  3. Trader logs in using his personal cTrader profile and allows permissions.

  4. After that, the trader is redirected back to the service side with authentication code which can be exchanged with an access token. The access token allows the service performing operations with the trading account on behalf of the trader.


Application Authorization

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.

If you want to get an authentication token for a cTrader ID, you should follow the instructions described in OAuth Services Description section of API Reference.

But for testing our Open API while skipping the authentication flow, you can follow the steps described in the Playground section. This authentication token will be requested for our test application "Test Partner" registered in demo connect site.

Select your application from the Applications section and click Playground next to it. Select the scope you need - Trading or Accounts - and click Get Token.

Note 1. 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.

Note 2. If you are not aware of OAuth technology, please check the OAuth standard reference RFC6749: The OAuth 2.0 Authorization Framework.

Authorization Flow

When the newly added application is activated, you can proceed with getting your access token and authorizing the accounts.

Click Playground next to the required application. Here you can find your access and refresh tokens and authorize the accounts. Select the scope of permissions and click Get Token.

Note that there are two scopes of permissions available for the OAuth 2.0 requests:

  • Accounts - to request for access to the Account Info (trading history, positions, pending orders, etc.)

  • Trading - to request for permissions to perform trading actions on behalf of Account owner (send market and pending orders, receive trading events, etc.)

Hide or show the client cTrader ID and email to the app, select the accounts that you would like to enable authentication for, and click Allow Access.

The API uses cTrader ID as a trader's personal profile identifier to log in to cTrader Platform environment. For more details please check the official OAuth 2.0 Authorization Framework reference: RFC6749 The OAuth 2.0 Authorization Framework

Using OAuth examples

Note. If you intend to use an OAuth library to work with the Authorization server, please bear in mind that the library should be OAuth v2 draft 20 compatible.

There are two services provided:

  • Auth (e.g. https://sandbox-connect.spotware.com/apps/auth) - can be used to authorize resource (trading account) owners.

  • token (e.g. https://sandbox-connect.spotware.com/apps/token) - can be used to refresh or obtain tokens.

Obtaining and refreshing access token workflow:

Getting Authorization code URI:

https://sandbox-connect.spotware.com/apps/auth?  
client_id={your Partner's Id here}&  
redirect_uri={redirect_uri}&  
scope=accounts

Example:

https://sandbox-connect.spotware.com/apps/auth?client_id=7_5az7pj935owsss8kgokcco84wc8osk0g0gksow0ow4s4ocwwgc&redirect_uri=http%3A%2F%2Fwww.spotware.com%2F&scope=accounts

Exchanging Authorization code with access_token and refresh_token:

https://sandbox-connect.spotware.com/apps/token?  
grant_type=authorization_code&  
code={authorization_code}&  
redirect_uri={redirect_uri}&  
client_id={your Partner's Id here}&  
client_secret={your Partner's Secret here}

Note. {authorization_code} placeholder should be replaced with the actual authorization code from getting authorization code response.

Example:

https://sandbox-connect.spotware.com/apps/token?grant_type=authorization_code&code={authorization_code}&redirect_uri=http%3A%2F%2Fwww.spotware.com%2F&client_id=7_5az7pj935owsss8kgokcco84wc8osk0g0gksow0ow4s4ocwwgc&client_secret=49p1ynqfy7c4sw84gwoogwwsk8cocg8ow8gc8o80c0ws448cs4

Note. Please bear in mind that access tokens have their expiry time. When you get an error message about access token expiration you should generate message to refresh the last one with refresh token request. Please see the details below.

Refreshing token URI:

https://sandbox-connect.spotware.com/apps/token?  
grant_type=refresh_token&  
refresh_token={refresh_token}&  
client_id={your Partner's Id here}&  
client_secret={your Partner's Secret here}

Note. {refresh_token} placeholder should be replaced with actual refresh token.

Example:

https://sandbox-connect.spotware.com/apps/token?grant_type=refresh_token&refresh_token={refresh_token}&client_id=7_5az7pj935owsss8kgokcco84wc8osk0g0gksow0ow4s4ocwwgc&client_secret=49p1ynqfy7c4sw84gwoogwwsk8cocg8ow8gc8o80c0ws448cs4

Note. Before start using OAuth services please read the following section of the guide: OAuth Services Description for more details.

Get access to accounts via OAuth

When a trader decides to allow a 3rd party application to get access to their trading account they should be taken to Open API OAuth authorization server. The trader will enter his cTrader ID credentials there to be logged in and then will be asked for what kind of resources he would like to grant. After the permissions are taken the OAuth backend generates an access token which relates to the allowed resources. Then the access token is sent back to the 3rd party's backend.

After 3rd party's application gets the access token it can use all of the granted resources of the trader without any additional requests for that.