Skip to main content
Kinetic Community

Sessions

This resource describes the client authentication process for the Kinetic Response API.

Validating the Domain

A route exists that lets the client validate that the domain name being used is correct.

 

HTTP Request

Method: GET

URL: /api/v1/valid

Headers: Content-Type application/json AND Accept application/json

URL Params: None

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code. 

A failed API response might result in a 500 response or perhaps a multitude of other errors if the domain is in fact not correct.

Response Codes

Response Code Reason
200 Successful request.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.

 

Creating a Session

For a client to access the Kinetic Response API they must first create a Session. This involves the client submitting their credentials (an email / password combination) to the server. In response the client receives a Session which includes user information, details about the Session and an auth_token (Sometimes referred to as a Bearer token).

 

HTTP Request

Method: POST

URL: /api/v1/sessions

Headers: Content-Type application/json AND Accept application/json

URL Params: None

Body Content:

{
    "user_login": {
        "email": "me@mycompany.com",
        "password": "password"
    }
}

 

Parameters

 

Route Parameter Name Description Required / Optional
EMAIL The email of the user logging in Required
PASSWORD The password of the user logging in Required

 

 

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body.  The JSON response object will contain the following information:

 

Response Property Description
auth_token The authorization token used in subsequent API calls to validate user's authenticity. 
user The properties in the user object represent profile information entered by the user.

 

Example Response:

{
    "demo_mode": false,
    "success": true,
    "auth_token": "dasd5fRd9656f9593c8a928c40d36939824558db950bacf8aa2a4e18144328G",
    "expires_in_seconds": 7200,
    "refresh_token": "58631efeb8b88bdb44be037d1f83b8e55827f7a033933bc9aeec1525s45f",
    "user": {
        "id": 784,
        "email": "me@mycompany.com",
        "name": "Mary Manager",
        "type": "SuperAdmin",
        "created_at": "2014-04-08T14:09:17.519-05:00",
        "updated_at": "2015-03-30T10:12:06.924-05:00",
        "status": "Active",
        "deleted_at": null,
        "guid": "bf8c0c74-bce7-4845-864R-a3d56de548e1",
        "time_zone": "Central Time (US & Canada)",
        "company": "My Company",
        "phone": "6125551212",
        "title": "Manager of IT"
    }
}

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Example of a failed request:

Response Code: 401 

Response Body:

{
    "success": false,
    "message": "Error with your login or password"
}

 

Response Codes

Response Code Reason
200 Successful request.
401 The email / password combination provided were not valid.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.

 

Example

The session information is used in almost all subsequent calls to the API.   The steps to authenticate and then make other calls are:

1. A client creates a new session by passing in their credentials to /api/v1/sessions.  A number of tokens are returned via JSON along with the User object for the session.  The primary token required is the auth_token.  

2. This auth_token is then passed along on subsequent requests via an Authorization header.  The format of the authorization value is: Bearer <auth_token> (Bearer 704f5beb2e0c46cbcfe20a6992ce16e410c4f5af335b5d9353f647370eb5ef2).

3. The server will periodically invalidate the auth_token which will require to client to resubmit their credentials to obtain a valid auth_token. The client will be informed of the auth_token expiration by receiving a 401 response when trying to access an API route using their auth_token.