Introduction
All Saxo Bank's Open API endpoints require that the calling application includes an Open API access token. The method through which the application gets this token follows the framework specified in the Oauth 2.0 protocol draft. We have however implemented a few variations in order to make certain scenarios easier to implement and to be able to combine the OAuth flows with a SAML 2.0 based SSO flow.
The following describes the basic steps for an application to be able to obtain a valid access token.
If you just want to get started quickly, you can use the "Open API token" feature on the developer portal to get an access token for your account on our simulation system. This has only has a one time lifetime, but it saves you having to implement a full authentication flow.
Get Open API Application Key
To get started you must have an Open API Application Key and Application Secret. You get this by contacting Saxo Bank, as explained in the introduction.
Recommendations on AppKey and AppSecret security
You should never expose your AppKey and AppSecret to your users, for instance by embedding them into a JavaScript-Application.
If any 3rd party can access your AppKey and AppSecret, they can access Open API as if they were your application, and potentially cause havoc that will be attributed to your application. If you are implementing only a JavaScript Application, You should still keep the AppKey and AppSecret on your server and only expose the AccessToken to JavaScript Application, for instance by a web service.
Get Access Token from Authentication Server
Depending on your application type you must go through one of the login scenarios described below. This will give you an access token and possibly a refresh token.
Access Token Contents and Interface Classification
The access token contains a number of properties, which affect how an Open API endpoint responds to a request.
The table below is only for informational purposes. It is not the intention that a client application should try to decrypt and/or interpret the contents of an access token, and Saxo Bank may change to contents and format of the token at any time.
| Property | Meaning/Determines |
|---|---|
| "UserId" | Identifies the user on behalf of which this call is being made. This obviously controls which accounts can be accessed. |
| "AppId" | Identifies the application. (Your application in this case). |
| "Claims" | Open API resources are grouped by "access level" (Public, Restricted, Community, Personal, Confidential). For each of these access levels the claims specify if the calling application is allows to:
|
| "LifeTime" | When is this token no longer valid. |
The contents of the access token depends on how your application has been configured, when it is set up in Saxo Bank's security system. You will receive information about the claims allocated to your application along with your application key and secret.
When a request is made to Open API endpoint, the claims in the token are matched with those required by an individual endpoint. These requirements are documented in the reference documentation in the "Resource Info" box.
For example, in order to place a trade, your access token must have access "Write" to Open API endpoints marked "Personal".
Pass Access Token to an Open API Endpoint
Your application must include the access token in every request to an Open API endpoint. The access token may be used multiple times as long as it is still valid.
Refresh Access Token, if Necessary
Access tokens have limited lifetimes. If your application needs access to an API beyond the lifetime of a single access token, it can either:
- Go through the complete login flow again
- Use a refresh token to request a new access token. Using a refresh token is much simpler as it requires no user interaction. Under certain circumstances it even allows an application to get a new access token after the user has logged off. This is very useful for applications which monitors a portfolio or which conduct automatic trading.
Make sure you store refresh tokens in a secure long-term storage. You may continue to use them as long as they are valid. Every time you use a refresh token to get a new access token, you also get a new refresh token, this refresh token replaces and invalidates the previous refresh token.
Single Sign-On and Federated Single Sign-on
The authentication protocol actually supports both Single Sign-On and Federated Single Sign-on. It also has full support for Saxo Bank's White Label installations. These are however advanced topics which require extra development steps, exchange of certificates etc.. These will be discussed directly with the individual development team when the need has been identified.
Login Scenarios
Web Server Applications
Web Server Applications use the OAuth 2.0 Code Flow to obtain access tokens. The authorization sequence begins by the user agent being redirected to Saxo Bank's SSO system.
Saxo Bank's SSO system will authenticate the user and return an extended SSO token to the client application. This extended SSO token includes an OAuth authorization code.
At a later stage the Saxo Bank authorization servers will also prompt the user to accept/reject access for a particular application, which is standard behavior in a full Oauth 2.0 implementation.
The authorization code is then exchanged for an Open API access token (and possibly an Open API refresh token) by the application.
The web server may then call Open API directly, or (which is most common) forward the access token to the user agent, which may then call Open API.
When necessary, the client application may use the refresh token to obtain a new access token.
For details see the webserver application login documentation.
Native Applications
Installed applications use a flow very similar to the flow for web server applications. It assumes that the application has access to a system browser, or has a browser embedded as a web view.
An installed application must embed the application key and application secret in the application code, or it must reach back to it's own back-end server when completing the AuthCode-to-access token exchange. The client application is required to take reasonable appropriate measures to protect the application key and secret from discovery. Saxo Bank retains the right to revoke an application key/secret if it is found to have been disclosed and abused.
Again the authorization sequence begins by the user agent being redirected to Saxo Bank's SSO system.
Saxo Bank's SSO system will authenticate the user and return an extended SSO token to the client application. this extended SSO token includes an OAuth authorization code.
The authorization code is then exchanged for an OpenAPI access token (and possibly an OpenAPI refresh token) by the application.
For details see the installed application login documentation.
Native Applications - Certificate Based Authentication
Server applications may use certificate based authentication to obtain an Open API access token, without an actual user having to authenticate.
Currently Certificate-based Authentication is only available in our LIVE environment, and it is only available to select IBs and White Label Clients upon request.
In the certificated based authentication flow, the server application uses certificates to create a signed and encrypted request to the Saxo Bank authentication and authorization server. The request includes the the id of a user in the Saxo Bank system along with the application key and secret. The Saxo Bank authentication and authorization server will then provide an access token and optionally a refresh token in return.
For details see the certificate based login documentation.