Developer Zone

Authentication

Before being able to request any data, one needs to authenticate with the API and get a session ID. The session ID can be retrieved either as part of the JSON response, or else as a cookie.

If authentication is not done, further requests will be rejected. If a POST request for a report is done and no authentication has been made, a 401 error code will be returned. If the same request is done using GET, instead of an error, a 302 redirect is returned to the authentication page.

POST /auth/login

Authenticate a user by verifying username and password.

Request JSON Object:
 
  • user (string) – The username of your Usage Intelligence user account
  • password (string) – The corresponding password of your Usage Intelligence user account
  • useCookies (boolean) – Optional parameter to specify whether the response should set a cookie (if true), or include the session ID as part of the JSON response (if false). Default is false.
Request Headers:
 
  • Content-Type – Can be set to application/json or text/javascript
  • Accept – Should be set to text/javascript
Response Headers:
 
Status Codes:
Response JSON Object:
 
  • status (string) – Contains OK if successful or SYNTAX ERROR or AUTH ERROR.
  • reason (string) – Present only if status is not OK. Contains error message (reason).
  • sessionId (string) – Present only if status is OK and useCookies is false. Contains session ID to be used in all further requests.

Example request:

POST auth/login  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "password": "mypassword1",
    "useCookies": false
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK",
  "sessionId": "VSB8E2BzSC2eZSJm4QmTpA"
}

Logging out

In order to log out, it is required to invalidate the user session that was created when logging in. If cookies are being used, the cookie will also be invalidated. Two options for logging out are being offered - either invalidate a single session or else, invalidate all sessions that are active on your user ID.

Invalidate a single session

POST /auth/logout

If no JSON data is sent, the system expects to find a valid authentication cookie. If such a cookie is found, the cookie is deleted, and the session is invalidated from the server. If JSON data is sent, then the session and user ID are read from the JSON object as described below.

If this request is done via POST, then a JSON response as described below will be returned. If GET is used, the response is not in JSON but in user-friendly HTML. If you are using GET and still would like to receive a JSON response, add the parameter “resultFormat=raw” so the URL should be https://api.revulytics.com/auth/logout?resultFormat=raw

Request JSON Object:
 
  • user (string) – The username of your Usage Intelligence user account.
  • sessionId (string) – The sessionId obtained via POST /auth/login.
Request Headers:
 
  • Content-Type – Can be set to application/json or text/javascript
  • Accept – Should be set to text/javascript
Response Headers:
 
Status Codes:
Response JSON Object:
 
  • status (string) – Contains OK if successful or SYNTAX ERROR or AUTH ERROR.
  • reason (string) – Present only if status is not OK. Contains error message (reason).