2.1. Get a new Session Token.
GET GetSessionToken
Description: Use your email address and password (or your API key) to return a session token that is required to access all market data from the API. This is usually the first API request made as a session token is required for most API requests.
API Usage: This endpoint uses zero API calls. Please refer to section 8.2 for more details on API rate limits.
GET Sample Requests:
GET https://[server]/GetSessionToken?email=myemail@mywork.com&passsword=mypassword&Minutes=30
or
GET https://[server]/GetSessionToken?APIKey=[YOUR-API-KEY]&Minutes=30
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| String | Your registered email address (sent with the password). | |
| Password | String | Your login password (sent with the email parameter). |
| APIKey | String | Your API key can be sent instead of your email and password. |
Optional Request Parameters
| Parameter | Type | Description |
|---|---|---|
| Minutes | Integer | The number of minutes life a session token has (Default is 30. Minimum is 1. Maximum is 1440 or one day (24 x 60 minutes). The token life is reset with each valid API command made (commands that use the session token) and can be manually reset to full life with the RenewSessionToken API command. |
Response Parameters
| Parameter | Type | Mandatory | Description | |
|---|---|---|---|---|
| 1 | ServerDateTime | String | Yes | The server UTC date and time as an ISO 8601 string. |
| 2 | TimeStamp | Float | Yes | The server date and time as a Julian date. |
| 3 | ExecutionTime | Float | Yes | The number of milliseconds taken to process the request. |
| 4 | Result | [Object] | No* | If the request is
a success, a Result
object is returned. See the 'Note' and the‘Result Object‘ table below for more details. |
| 5 | Errors | [Object] | No* | If the request
fails, an 'Errors' object is returned. See the 'Note' and the ‘Errors Object‘ table below for more details. |
A successful API request will return a Result object with the requested payload or an 'Errors' object detailing the issue that caused the error.
Tips:
- Your password can be changed using the 'Forgotten password' link on the login page at www.sarus.com.
- You can also change it at by logging in at sarus.com and selecting the 'Change Password' menu option from your ‘My Account' menu panel.
Result Object
| Parameter | Type | Mandatory | Description | |
|---|---|---|---|---|
| 1 | LastActive | String | Yes | The date and time that the API key was last used
(as an ISO 8601 string). E.g. 2017-10-17T15:44:50Z. |
| 2 | SessionToken | String | Yes | A session token string. A session token will automatically renew to full life when used successfully in any valid API request. |
| 3 | SimulatedAccess | Boolean | No | This optional parameter is returned only if true. If true, this is not a ‘live’ account and the prices and values returned are simulated and will change with each request. These simulated values are meaningless and intended for testing only. They must not be used in any work related activity other than for testing the API functionality. |
| 4 | Remaining | Long | Yes | The remaining token life in milliseconds. |
Errors Object
| Parameter | Type | Description | |
|---|---|---|---|
| 1 | Status | Integer | HTTP status code. |
| 2 | Detail | String | Description of the status code error. |
Possible Status codes in the 'Errors' object
| Code | Description |
|---|---|
| 400 | Missing argument(s): APIKey or Unknown argument: + the parameter name. |
| 401 | Invalid credentials. Check API key. |
| 403 | The user is inactive. |
| 405 | Method [request] not allowed. |
| 500 | Server may be down for maintenance. |
This is not an exhaustive list and additional error codes may be returned. The Errors Detail field will return request specific error information.
Possible HTTP response codes
This
endpoint returns 200 for
success.
You can get HTTP client network errors or server
errors from any API request. You should check
with your network or IT colleagues in case the issue is a
local one.
All server generated errors will return an 'Errors'
object that will give specific details about the error.
A full list of HTTP codes and their meanings is available here,
Success and fail examples
The sample requests a token using the registeredemail, password and token life minutes as parameters.
Sample Request:
GET https://[server]/GetSessionToken?email=roger@concisecomputers.com&password=pass&Minutes=30