Overview

The API is built as a web service interface using Simple Object Access Protocol (SOAP) and uses Extensible Markup Language (XML) message formats for exchanging messages between the White Label and Saxo Bank.
The communication between the White Label and the CMS API is encrypted using Secure Socket Layer (SSL) An X509 client certificate (pfx) provided by Saxo Bank is used along with the server user's username and password to establish the identity of the White Label.
The White Label Account Structure is built as a tree-structure and the server user has access to all customers under the branch it is configured on.
Average response time varies, depending on the type of request, the amount of customers in the White Label's account structure and the amount of data requested. For example in a tree with 1000 counterparts, the average response time is;

• Create Counterpart – 15 seconds
• Retrieving account data information – 200ms

The CMS API is based on a synchronous request/response protocol.
The CMS API is divided into two services where each is in a test and live version.

 The four CMS Web Services can be reached by the following URLs:

The White Label will be configured with two users, one for the CMS Test Service and CMS Test Login Service and one for the CMS Live Service and CMS Live Login Service. One X509 client certificate will be issued for each user.

CMS Test Service and CMS Test Login Service

The CMS Test Service allows the White Label to test the same calls as available in the CMS Live Service, but without database commitment.
The White Label will receive a Test Server User, which can used to call the Services in the CMS Test Service.
The CMS Test Service operates on the White Label's live account structure, and test results will validate the business logic of the requests as well as its technical syntax. However, it will not commit any changes to the database.
The CMS Test Service results that are presented to the White Label are identical to the results of requests in the CMS Live Service.

CMS Live Service

The CMS Live Service is used by the White Label to create customers, transfer cash and to retrieve live customer data.
The White Label will receive a Live Server User, which can be used to call the Services in the CMS Live Service.
The CMS Live Service gives access to three areas of functionality;

1. Account Information
2. Customer Creation
3. Cash Transfers

CMS live login Service

The CMS Live Login Service is used for Authentication of the White Label, change of server password and exchange of session tickets.
The CMS Live Login Service gives access to

1. Login request
2. Change server user password.

The rest of the requests are not relevant for the White Label. 

Authentication

In order to access and communicate with the CMS API, the White Label must be authenticated via the following:

• X509 Client Certificate
• Username
• Password

The following sections describe the requirements for a successful authentication to the CMS API.

Certificate

An X509 client certificate must be installed on the server communicating with the CMS API. Saxo issues the certificate and sends the White Label two emails; one with the X509 client certificate and one with the password for the certificate. The certificate must be installed on the server communicating with the CMS API.
In case of a dual or multiple server setups, the White Label can install the certificate on all servers with the limitation that requests will only be accepted from one server at the time. If the White Label requires multiple servers to use the CMS API simultaneously, two or more users and certificates can be created, so each server has its own certificate and user.
The X509 client certificate is valid for one year and a replacement certificate will be provided by Saxo one month, before the expiry of the current certificate.

Username and password

The White Label has chosen its username and a first time password for the CMS API via a request form and only the username will be communicated email to the White Label. These credentials do not only identify the White Label, but also grants access at the appropriate level of the White Label's account structure. Usual practise is that the server user is created at the top, so is has access to all branches and underlying customers, unless otherwise requested.

Hash password

For security reasons the API does not accept passwords in clear-text. Therefore the passwords must be hashed using the SHA265 algorithm. Saxo provides a Windows Console application, HashPassword.exe, which can be used for generating a hash for a password.

Login

When the White Label logs on to the CMS API with a username and password using the CMS Live Login Service call (LoginRequest), information retrieved from the X509 client certificate is compared to what is stored in the CMS API database. If the login credentials match, the login is successful and the server returns a ticket (SessionID).

Change Password

The server user is required to change the password at first login.
The password is valid for 3 months after which the White Label is required to renew the password. Hence the server user must be prepared to change the password at regular intervals in order to continue being able to use the CMS API. If the server user does a login with a password that has expired, an exception code will be returned informing the server user that the password has expired.

Session management

The ticket returned in the response of a successful login must be passed along in the SOAP header in all subsequent web service calls. This ticket is valid for 8 hours and after that the server user needs to request a new ticket from CMS API using LoginRequest. If the server does a request with a ticket that has expired, an exception code will be returned informing the server user that the SessionID has expired.
The SessionID cannot be renewed within the valid 8 hours. A LoginRequest within the timeperiod, will return the same sessionID, The White Label is therefore required to handle the session expiry exception when it occurs.
If a request is sent at the same time as the ticket expires, then the same request has to be sent again after obtaining a new sessionID.

CMS live Service Requests

The available Web Service Requests in CMS Live Service can be divided into three areas:

1. Account Information
2. Client Creation/Update
3. Cash Transfer

The below sections describe each available request available and the purpose of the functionality in each area.

Account information Module

The Account Information module allows you to retrieve information related to a counterpart/account, be it trading data or account structure data.
Here are few examples, which are not exhaustive, for the final usage of the AI module:

• Aggregation of account information for institutions with multi-brokers in order to provide a centralized view to their customers
• Publish account information to White Label's customer in the White Label's web site environment
• Integration with White Label's risk management systems, at the global institution level or at individual customer level
• Alerts in near real time in case of specific events (exposure increase, large trades …), albeit the usage of TENS, must be considered for this feature also.
• Integration with client CRM application, so it has account information in near real time.

Note: The AI module allows retrieving account information but it cannot be used to change the account's data.
The requests available within the Account Information module are:

Client Creation/Update Module

The requests available within the Client Creation/Update module are all related to creating and updating customer/accounts within the White Label's account structure.
The requests available within the Client Creation module are:

In the update scenarios no explicit verification is given that the update succeded. If a response is given, the update is a success. If an error occurs, an error is returned. See Section 5 for details.

Cash Transfer

The Cash Transfer requests enables the White Label to validate a cash withdrawal on a customer's account and transfer cash in or out of the client's trading account from and to the White Label's funding account.