Session Token

This s a documentation page for our shiny new REST API - you weren't meant to find it. This API isn't ready for public use yet. We're chopping and changing it a LOT as we grow it. So if you build something that uses it then it's very likely to break in a future update. Don't say you weren't warned!

URL:

https://api.kashflow.com/v2/sessiontoken

Method(s):

get, post, put, delete

Response Formats:

JSON or XML

Description:

Your requests to the REST API need to include a valid Session Token. The /sessiontoken method is used to acquire a Session Token.

This is a two step process.

Step 1 – Get a Temporary Token for use in Step 2
In the first step you send a POST containing username and password for the account.
If the credentials are valid then the response you receive will include a Temporary Token and 3 character positions that are to be used for the second step.

Step 2 – Exchange the Temporary Token for a Session Token
This must be completed within x minutes of step 1 or the temporary token you were issued will expire.
As an additional security step, we require specific characters of the users memorable word. The position of those characters was given to you in the first step.
So if the memorable word is “pineapple” and we asked for characters 3, 4 and 6 then we expect to receive N, E and P (case insensitive)
The whole response in Step 1 and the relevant characters, along with the temporary token are sent as a PUT request. If everything is correct then the response will contain a Session Token that you can use to authenticate the user for all over requests.

Alternative approach
You may have been issued with an External Token. You can use the GET request to swap this for a Session Token.
You would rarely have cause to use this approach as it’s currently only used by our internal systems to validate a user against the REST API in when we have already authenticated them elsewhere on our platform.

The Session Token will expire if it’s not used for x minutes. Alternatively, you can cause the Session Token to expire immediately by sending a DELETE request.

Example requests and response for these methods are detailed below.

POST Operation

Step 1 – Returns a temporary token with the memorable word positions.

Example request for POST of login


{
   "Password":"password",
   "UserName":"admin"
}

Example response for POST of login


{
   "HasTemporaryPassword":false,
   "IsAdmin":true,
   "PackageName": "Business",
   "PartnerBrandingOptOut": true,
   "MemorableWordList": [{
        "Position": 2,
        "Value": ""
    }, {
        "Position": 3,
        "Value": ""
    }, {
        "Position": 4,
        "Value": ""
    }],
    "PartnerId": 3,
    "SubscriptionExpired": false,
    "TemporaryToken": "c3ce04a3-65b3-48bb-a3b9-366769359c56"
}

PUT Operation

Step 2 – Returns a session token, for the requested temporary token and memorable word characters for the positions specified on the post response.

Example request for PUT of login


{
   "TemporaryToken":"b9494c49-6203-4127-bbbd-a0414e38f8dc",
   "MemorableWordList":[
      {
         "Position":3,
         "Value":"a"
      },
      {
         "Position":4,
         "Value":"a"
      },
      {
         "Position":1,
         "Value":"a"
      }
   ]
}

Example response for PUT of login


{
    "CompanyName":"KashFlow Accounting Software",
    "IsAdmin": true,
    "SubscriptionExpired": true,
    "PartnerId": 3,
    "PackageName": "Business",
    "PartnerBrandingOptOut": true,
    "SessionToken": "f998b09a-6019-4f2f-a0c2-447101497859",
    "StartPageUrl": "Suppliers",
    "SubscriptionExpiryDate": "2012-02-02 12:00:00",
    "HasTemporaryPassword" : false 
}

GET Operation

Alternative Method – Retrieves a session token for specified external token.

URL : /sessiontoken?externalToken={externaltoken}&uid={userid}

Example response for GET of login


{
    "SessionToken":"aadb61d4-031c-4fa5-ace6-03bbb29a6db2"
}

This method can be used to retrieve session token for any of the user’s associated accounts.
{username} in the URL would be replaced by valid username of associated account.
Unlike other API methods on this page, this method requires valid authentication token to be passed in authorization headers.

URL : /sessiontoken/{username}

Example response for GET of login


{
    "SubscriptionExpired": true,
    "PartnerId": 0,
    "SessionToken": "1f44634f-ae75-42c9-80ff-9ea21cd87e61",
    "StartPageUrl": "Suppliers",
    "SubscriptionExpiryDate": "2012-12-31 12:00:00",
    "UserName": "vijayendra",
    "HasTemporaryPassword" : false
}

DELETE Operation

Deletes a session token by following url –

URL : /sessiontoken/{sessiontoken}

{sessiontoken} is session token which is acquired in the previous operation (PUT).

Example request for DELETE of login


{
    "SessionToken":"34asds34-867c-5fad-jhg6703bbb29akj5d"
}

See how IRIS KashFlow works with your business and your books