Sessions

The Session module allows you to mint and destroy session tokens.

The idea being that rather than needing to send explicit authentication details with every request, you can send them once to mint the token and then simply provide the token with each subsequent request.

An additional benefit of this is that it allows you to pass a users browser a sessionKey so that they can place requests themselves (perhaps via AJAX, or at a basic level, to simply load a chart).

 

Creating a Session Token

To create a session token, place a request to

/session/create

Within the JSON request, you must specify the following

  • ClientIP: The IP address that subsequent requests will originate from. This _must_ be correct, otherwise access will be denied

The token will be generated for whichever user is currently authenticated, so if you're using a site key to authenticate on behalf of a user, ensure your authentication headers include the user's key (See the Authentication documentation for more detail).

 

Response

The JSON response will be an array containing the minted token in key 0 and the expiry time in key 1;

{
"timestamp":1382057808,
"response":[
"eJw9jMsOgjAQRb+GLslMI3S66EJ0485o+IAKAxINwRYT+HtREjZnce7jyUvfeBQxDI13BFp0PHhUJMFYAhLTMrK\/cUqC5ykGn9kyk\/J8WZGpw0rCHJXO0chc\/6Q8ruR57COnrbS9kQXawiu\/P5wmbsplf6lw31aJ4+7\/2p5EeHU+PQKK1Hde17YlBdYwILaG0dUuqDvIYArtQNtQ8Bq6L577OhI=",
1382058708
],
"errors":null,
"error":0
}

Be aware that session tokens are only valid for 15 minutes once they've been minted

 

Destroying a Session

To destroy a session, place an authenticated request to

/session/destroy

Within the JSON request you must specify the Session token as DestToken. As an additional security measure (to prevent users from destroying other's sessions), you must also be authenticated (whether directly, or as a site on behalf) as the user the token was created for.

 

Response

{
"timestamp":1382057808,
"response":1,
"errors":null,
"error":0
}

Note: If you fail to authenticate as the user the session relates to, no error will be returned, the session will simply remain valid.

 

Errors

The following errors may be returned

  • Authentication Failed: The system was unable to authenticate your request, check you've sent valid auth headers with your create/destroy request
  • IP Not Specified: You didn't specify a ClientIP in your request. The token is locked to a specific IP for security reasons, so a token could not be minted.
  • Token Not Specified: You placed a destroy request, but didn't specify the session token.