Tradera Developer Program

Authentication and authorization 

To access any of the methods in the API, you need to identify yourself through an application id and a corresponding application service key. By registering an application in the developer center, you will receive an application id and a service key. The id and key then need to be passed to the server in one of two ways:

  1. As part of the URL: using appId and appKey URL parameters.
  2. As part of the SOAP AuthenticationHeader element: using the AppId and AppKey elements.

For methods contained in the RestrictedService, you need to get permission from the user before calling methods in their name. If you try to access a method without the right authorization, you will get a 403 Forbidden HTTP status code.

You get permission by asking the user to login with their Tradera credentials on a special sign-in page (https://api.tradera.com/tokenlogin.aspx). Here they will be asked to enter their credentials, and then a Token will be created for your application and this specific user. Every time your application wants to access a restricted method, the token need to be passed to the server in one of two ways:

  1. As part of the URL: using userId and token URL parameters.
  2. As part of the SOAP AuthorizationHeader element: using the UserId and Token elements.
The token is bound to a session specific secret key of your choosing.

Whether to display the token or not

When the application is set to DisplayToken in the Tradera system, the auth token and hard expiration date are included in the AcceptURL or RejectURL (if they are set). When disabled, the auth token information is not included, and your application needs to make a subsequent call to FetchToken to retrieve the auth Token.

There are three ways to approach token retrieval via sign-in redirect.

Option 1

This option is best suited for client applications which cannot (or choose not to) host an AcceptURL or RejectURL. In this option, the user is presented with a default message on a Tradera page (which states something to the effect of "thanks" and "you may close this window"). The calling application then calls FetchToken to retrieve the auth token. The same secret key is required in the sign-in URL and when calling FetchToken.

Figure 1
Figure 1: Sign-in flow ends on Tradera; use FetchToken to get token

Sample tokenlogin.aspx page URL:
https://api.tradera.com/tokenlogin.aspx?appId=XX&pkey=YY&skey=ZZ

XX
Your application Id.
YY
Your public key.
ZZ
The session specific secret key (skey) used by your application to identify the request. Tradera recommends an UUID, for example 77FA15BA-E13C-4D83-B6DC-E7F9FFB6601F. The skey's length must be between 32 and 255 characters.
Required settings
Accept URL
Empty string
Reject URL
Empty string
Show token
N/A (setting is not used in this scenario)

Option 2

This option is best suited for applications that can handle redirect URLs from Tradera yet do not wish to receive the auth token in that URL. After Tradera redirects the user, the application then calls FetchToken to retrieve the auth token. The same skey is required in the sign-in URL and when calling FetchToken.

While all options are secure, Tradera favors option 2 over option 3.

Figure 2
Figure 2: Sign-in flow returns user to web-application; use FetchToken to get token

Sample tokenlogin.aspx page URL:
https://api.tradera.com/tokenlogin.aspx?appId=XX&pkey=YY&skey=ZZ

XX
Your application Id.
YY
Your public key.
ZZ
The session specific secret key (skey) used by your application to identify the request. Tradera recommends an UUID, for example 77FA15BA-E13C-4D83-B6DC-E7F9FFB6601F. The skey's length must be between 32 and 255 characters.
Required settings
Accept URL
Valid URI, i.e. https://www.example.com/returnaccept.aspx
Reject URL
Valid URI, i.e. https://www.example.com/returnreject.aspx
Show token
Disabled

Option 3

This option is best suited for applications that can handle redirect URLs from Tradera and wish to receive the auth token in that URL.

Figure 3
Figure 3: Sign-in flow returns user to web-application and redirect URL includes token

Sample tokenlogin.aspx page URL:
https://api.tradera.com/tokenlogin.aspx?appId=XX&pkey=YY

XX
Your application Id.
YY
Your public key.
Required settings
Accept URL
Valid URI, i.e. https://www.example.com/returnaccept.aspx
Reject URL
Valid URI, i.e. https://www.example.com/returnreject.aspx
Show token
Enabled

Getting a Token via URL Redirect

Preparing the URL for User sign-in

To redirect a user to the Tradera sign-in page (in order to generate an auth token), an application must use this URL:

https://api.tradera.com/tokenlogin.aspx?appId=XX&pkey=YY

where:

XX
Your application Id.
YY
Your public key.

The resulting web page is a Tradera sign-in page. It also includes the name of the application and some special authorization-related text.

Optionally, the URL can include &ruparams=ruparams or &skey=skey or both, where:

  1. ruparams is any additional data that you wish passed back to your application via Tradera's redirect (for example, an identifier which the application can use via database lookup to identify the user associated with the returned token); it is not used in any way by Tradera.

    The application-specific data that is passed in ruparams may consist of zero or more pieces of information, each in a variable name and URL encoded value format. When Tradera redirects to the application's Accept URL, the value of ruparams is URL decoded into name/value pairs.

    For example, if the application sends this:
    ...&ruparams=VarA%3DB12309%26VarB%3DABC123
    Tradera returns this in the URL:
    ...&VarA=B12309&VarB=ABC123
  2. skey is an application-defined secret key for use in a non-web page solution for token retrieval.

    This token is required if the Show token setting is disabled. The value of the sid parameter must be between 32 and 255 characters. Tradera recommends using a UUID value to ensure uniqueness. The same skey is used when retreiving the Token via the FetchToken method.

The Form of the AcceptURL

Assuming that the user successfully signs in at the Tradera sign-in page and accepts the application representation terms, Tradera redirects the user to the application's Accept URL. This URL is supplied by the application's proprietors when registering the application and is maintained on file at Tradera for the purpose of this redirection during the token generation process. By default, the application can retrieve the token for the user from the Accept URL, although the application can specify in the application authentication data entry that it will be retrieving the token programmatically instead.

When Tradera constructs the URL for the application's Accept URL redirect, Tradera may append to the URL the following parameters: token, exp, userId and any ruparams that were passed in.

For example:

https://www.example.com/returnaccept.aspx?token=ABC...123&exp=2007-07-16T19:20:30.45+01:00Z&userId=0&VarA=B12309&VarB=ABC123

token
Contains the authentication token that the application uses to authenticate a user when making calls to Tradera RestrictedService API functions. In this example this is the abbreviated "ABC...123" (actual tokens are much longer). If the application configures the application authentication data entry to retrieve tokens programmatically, then this parameter is not included in the URL.
exp
Indicates the date the authentication token hard expires (in this example "2007-07-16T19:20:30.45+01:00Z"). This value is in the ISO 8601 standard format (YYYY-MM-DDThh:mm:ss.sTZD). If the application configures the application authentication data entry to retrieve tokens programmatically, then this parameter is not included in the URL.
userId
The user's Tradera Id

The application needs to parse these parameters and store them for later use when making API calls and for managing token expiration. There are a number of possible ways for the application to store this data, such as in a database table or in a cookie. Whatever means the application uses, it should be given the same data protection considerations as one would give to a login name and password.

When the application needs to make an RestrictedService API call, it would then retrieve the stored token (table, cookie, whatever) and use it in the method call.

The redirect URL follows standard URL encoding protocol. This means that the value in token needs to be URL decoded to get the actual token.

XHTML CSS