Skip to content

Getting Access

Overview

This article will explain how to obtain the access details needed to log into the system.

There are three methods that can be used to login.

  1. Plain username and password

  2. JWT Token

  3. OAuth Token

Using username and password - these are provided by FXCM, either by creating a demo account, or signing up for a real account.

You also need a URL and Connection Name for each of the environments.

Connection Name URL
Demo https://www.fxcorporate.com/Hosts.jsp
Real https://www.fxcorporate.com/Hosts.jsp

You can fetch a JWT token by accessing the endpoints that are described here https://endpoints-demo.fxcm.com/iam/swagger-ui/index.html and hitting the relevant endpoints with the relevant information, pulling down a JWT, and using that to create an API session.

Step 1

There are two different URLs, one for Demo (endpoints-demo.fxcm.com) and one for Real (endpoints.fxcm.com). for example: Curl 
curl -X 'GET' 'https://endpoints-demo.fxcm.com/iam/trading-systems/<username>' -H 'accept: */*'
or Request URL 
https://endpoints-demo.fxcm.com/iam/trading-systems/<username>
Where you replace the actual username of the account you wish to use.

Both of these requests wil return a JSON response. For example, the following is a real response from a Demo account: 

[
    {
        "tradingSessionId": "FXCM",
        "tradingSessionSubId": "CFDDEMO01",
        "properties": {
            "S": "RFhYb1RpaWVYQ0pDZVlUYUFPZ0FVTVp3c2t3TnFy",
            "PIN_SIZE": "0",
            "DESC": "CFDDEMO01",
            "PIN_REQUIRED": "N",
            "NAME": "CFDDEMO01"
        }
    }
]

If you do not receive this object in response in your code, you may need to add custom header to your request, eg: 'X-COOKIE-DOMAIN':'fxcm.com'

You must take the tradingSessionID, and tradingSessionSubId values, and store them into variables. This call also sets a cookie in the fxcm.com domain called 'XSRF-TOKEN'. You must store that value in a variable as well.

The following is an example of a Postman JavaScript script that would take the necessary values, and assign them to variables 

var xsrfCookie = postman.getResponseCookie('XSRF-TOKEN');
pm.environment.set('X-XSRF-TOKEN', xsrfCookie.value);

const response = pm.response.json();
sessionid = (response[0]["tradingSessionId"]);
pm.environment.set("tradingSessionId", sessionid);
subid = sessionid = (response[0]["tradingSessionSubId"]);
pm.environment.set("tradingSessionSubId", subid);

Step 2

Next we must sent a POST request to https://endpoints.fxcm.com/iam/authenticate/ or https://endpoints-demo.fxcm.com/iam/authenticate/, depending on whether your account is a Real or a Demo account.

This request needs to have to custom headers set:

  1. 'X-COOKIE-DOMAIN':'fxcm.com'
  2. 'X-XSRF-TOKEN': The X-XSRF-Token value we saved earlier.

The body of the request must have the following content in json format: 

{
    "loginId": "{{loginID}}",
    "password": "{{password}}",
    "tradingSessionId": "{{tradingSessionId}}",
    "tradingSessionSubId": "{{tradingSessionSubId}}",
    "appName": Custom name for your application
}
The following is a curl example: 
curl -d "{\"loginId\":\"U10D2460235\",\"password\":\"x3fAb\",\"tradingSessionId\":\"FXCM\",\"tradingSessionSubId\":\"U10D2\",\"appName\":\"Test\"}" -H "Content-Type: application/json" -X POST "https://endpoints-demo.fxcm.com/iam/authenticate" --header "X-COOKIE-DOMAIN:fxcm.com" --header "X-XSRF-TOKEN:7a4ff8cb-48a4-4e7d-b791-96e15e271e88"

Note

The quote characters may need to be prefixed with an escape character \ depending on your implementation.

This call will return your access token and refresh token in a json format. 

{
    "accessToken": "eyJraWQiOiJhY2Nlc3NfMCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0... ",
    "refreshToken": "eyJraWQiOiJyZWZyZXNoXzAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ... "
}
You can now use this access token to login.

Step 3

Note

An Access Token only is valid for 1 minute. You must continuously call the /refresh/ endpoint with the same 'X-XSRF-TOKEN' custom header, in order to get a new access-token back from the server.

Refershing your access_token is very simple. We must sent a POST request to https://endpoints.fxcm.com/iam/refresh/ or https://endpoints-demo.fxcm.com/iam/refresh/, depending on whether the access_token in question is from a Real or a Demo account.

This request needs to have to custom headers set:

  1. 'X-XSRF-TOKEN': The X-XSRF-Token value we saved earlier.

This call will return a new access_token value in the same format as in Step 2

{
    "accessToken": "eyJraWQiOiJhY2Nlc3NfMCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0... ",
    "refreshToken": "eyJraWQiOiJyZWZyZXNoXzAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
}
You can now use this access_token to login.

You can authenticate and authorize requests to the FCLite API using the method IFXConnectLiteSession.attach.

Class IFXConnectLiteSession is the interface that provides access to the trading system.

By integrating with our OAuth2 solution, you can an OAuth Token which can then be used to get JWTs for clients.

Pre-Requisites

To use this method, you will need a special client_id, client_secret and a redirect_url from FXCM staff. This is usually only provided to other brokers or vendors who wish to offer services to FXCM customers - this method is not intended for end customers themselves.

When requesting this type of account, you should provide the staff with a redirect_url where users will be redirected back to after they have authenticated. This is where you will capture your OAuth token.

Step 1

The first step of this authentication method is to redirect the user to the FXCM OAuth login page https://{fxcm_domain}/oauth/authorize?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&scope=openid%20trading.

There are three parameters here to pass in this URL.

  1. client_id
  2. redirect_url
  3. fxcm_domain
    • Production Real: oauth.fxcorporate.com
    • Production Demo: oauth-demo.fxcorporate.com
    • UAT: oauthu.fxcorporate.com
    • QA: oauthq.fxcorporate.com

Once the user has been redired to this URL, they will enter their standard login and password from when they created a demo account, or signing up for a real account.

The user will be redirected back to their redirect_url with a code appended to it eg: http:\\myside.com?code=xxxxx

Store the code as you will need it for the next step.

Step 3

Finally you must then send a POST request to https://{fxcm_domain}/oauth2/token using the specified domain from the list above. The body of this request must contain.

Required Parameters:

  1. code: value from code parameter

  2. grant_type: authorization_code

  3. client_id: string value provided by FXCM

  4. client_secret: string value provided by FXCM

  5. redirect_uri: exact redirect_uri that you provided FXCM

Optional parameters:

  1. code_challenge_method= Set to S256 to indicate that SHA-256 hashing is used to transform the code verifier

  2. code_challenge= The BASE64URL-encoded SHA-256 hash of a random 32 bytes called code verifier which the client must generate and store internally and which is intended to prevent code injection and CSRF attacks. Originally specified in the PKCE extension (RFC 7336) to OAuth 2.0

  3. state= Optional opaque value set by the client which the authorisation server will echo verbatim in the authorisation response. Enables the client to encode application state information to appear at the redirect_uri

  4. nonce= String value used to associate a Client session with an ID Token, and to mitigate replay attacks

You will receive a json response to your request.

{
    access_token: access_token, 
    refresh_token: refresh_token, 
    token_type: 'Bearer'
}
Now that you have the access token (which is valid for one minute) and the refresh token which can be used to get a new access token, you can now login.

Table of Contents