Tradera Developer Program

For methods contained in the RestrictedService, you need to get permission from the user before calling methods in their name. You do this by asking the user to login with their Tradera credentials on a special sign-in page (http://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.

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

Sample tokenlogin.aspx page URL:
http://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

Sample tokenlogin.aspx page URL:
http://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

Sample tokenlogin.aspx page URL:
http://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:

http://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.