OAuth Services Description

Quick Introduction to OAuth services

This section describes how OAuth works within the Open API and how third-party service providers can use it.

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

OAuth implementation of the Open API has two logical parts:

  1. OAuth Content services - allow to obtain access to resources themselves.
  2. OAuth Authorization services - allow to ask for the resource owners authorization and obtain an access token to get access to content of their resources on behalf of the trader.

Content services of Sandbox version are available by address authorize https://sandbox-api.spotware.com/

Communication with resource (e.g. trading account) owner looks like following:

  1. Trading account owner decides to use your service by clicking some action button on your site.
  2. The service generates a request to the Open API 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 to perform operations with the trading account on behalf of the trader.

The API uses cTrader ID as a trader's personal profile identifier to log in to cTrader Platform environment.

Learn more about cTrader ID here.

You can try all steps described above in the Playground section of the guide. It may help you to get better idea how to integrate this flow into your product.

For more details please see the official reference: RFC6749 The OAuth 2.0 Authorization Framework

Scopes of permissions

There are two scopes available:

  • accounts - to request for access to Account Info (trading history, positions, pending order, etc.)
  • trading - to request for permissions to trade on behalf of Account owner (Send market and pending orders, receive trading events, etc.)

Using OAuth examples

NOTE: If you intend to use 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:

  1. auth (e.g. https://sandbox-connect.spotware.com/apps/auth) - can be used to authorize resource owners;
  2. token (e.g. https://sandbox-connect.spotware.com/apps/token) - can be used to perform refresh tokens operations, etc.

Below is a brief example of the flow how to obtain access token and to refresh one.

Obtaining and refreshing access token workflow:

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

e.g.:

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 & 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}

e.g.: NOTE: {authorization_code} placeholder should be replaced with actual authorization code from getting authorization code response.

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 the 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 example:
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}

e.g.: NOTE: {refresh_token} placeholder should be replaced with actual refresh token.

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

If you have any questions feel free to contact us. Please direct all your questions to connect@spotware.com

See next chapter "Accounts API" to learn available functions of the Open API in more details.