Session API

Introduction

Session management describes the API requests needed to manage LiveVox API sessions, including logging into the LiveVox platform to create a new session, logging out an active session, listing active sessions, and getting details of an active session.

The Session API has two separate methods that allow either LiveVox Users or Agents to log in and create a new session. This allows API consumers to build a variety of applications that can accept either LiveVox Agent credentials or LiveVox User credentials and generate a Session ID. The API methods that can then be used with that Session ID will depend on whether the session was generated by an Agent or a LiveVox User. If it was generated by a LiveVox User, the User's security role will impact what API methods can be accessed with that Session ID. See the documentation of each API and API method, where this information is described.

For a general overview of the LiveVox APIs, include security aspects, see the LiveVox API Overview.

Prerequisites

To obtain an Access Token that is used in API requests, you must have an active subscription to the Configuration API. See Access Tokens for details.
All messages in this API may be subject to rate limits and other restrictions.

LV-Session Header

Other than the login, IsSessionValid, ChangePassowrd, and Logout requests, all other requests to the Session API, as well as all requests to all other LiveVox APIs, require that a Session ID be passed in with the request, in an HTTP Header. The Header field name is LV-Session and the value will simply be the sessionId. For example:

LV-Session: 38de9bcc-7425-4392-b821-99026632c369

Session Expiration

The session expiration is based on its usage. As long as a session is used once in a 2-hour rolling window, it will remain valid. The only exception to this is when the user's / agent's password expires or changes, at which point the user/agent will need to log in again using their new credentials and obtain a new session.

Multiple requests to log in using the same token, username, and password return the same valid session ID.

User Roles

The login request and Change Password request may be used by a LiveVox User or Agent. For all of the other requests, the user making the request must be a LiveVox User belonging to either the Sysadmin or Superuser role.

API Methods

Session Management

Change Password

Description: Allows a LiveVox User or Agent to change their password.

Method: POST session/password

Parameters:

None

Body:

Key or Attribute	Type	Mandatory?	Description
clientName	String	Yes	Name of LiveVox Client to which the User or Agent belongs.
userName	String	Yes	Name of the LiveVox User or Agent who wants to change his password.
password	String	Yes	Current password of the LiveVox User or Agent.
newPassword	String	Yes	New password of the LiveVox User or Agent. The password must comply with the same rules as when a LiveVox User or Agent is created or updated through the LVP GUI. Specifically, the password must be a minimum of 8 characters, containing at least 1 digit and cannot match any of the previous 4 passwords for the User or Agent.
agent	Boolean	No	If set to `true` the password update is for an Agent. If not included in the request it defaults to 'false' meaning that the password change is for a User.

Response Code: 204 No Content

Body:

None

Change the password of a LiveVox User

#Request (JSON)
POST /session/password
Host: localhost.com
Content-Type: application/json
Accept: application/json

{"clientName": "ACME",
 "userName": "john_doe",
 "password": "odPaSSW0rd",
 "newPassword": "newPaSSW0rd"} 

#Response (JSON)
204 No Content

CODE

Change the password of an Agent

#Request (JSON)
POST /session/password
Host: localhost.com
Content-Type: application/json
Accept: application/json

{"clientName": "ACME",
 "userName": "john_doe",
 "password": "odPaSSW0rd",
 "newPassword": "newPaSSW0rd",
 "agent": "true"} 

#Response (JSON)
204 No Content

CODE

Is Session Valid

Description: Checks if a session is still valid.

Method: GET /session/validate/{session}

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory	Description
session	sessionId	String	Yes	ID of the session you want to check.

Body:

None

Response Code: 204 No Content or 404 Not Found

Method will return a '204 No Content' if the session is still valid, while an invalid session will return a '404 Not Found'.

Body:

None

Session is still valid

#Request (JSON)
GET /session/validate/a3104123-de21-4b74-8efc-8771fa4c8455
Host: www.livevox.com
Content-Type: application/json
Accept: application/json 

#Response (JSON)
204 No Content

CODE

Session is no longer valid

#Request (JSON)
GET /session/validate/a3104123-d233-4b74-8efc-8771fa4c8455
Host: www.livevox.com
Content-Type: application/json
Accept: application/json 

#Response (JSON)
404 Not Found

CODE

Description: Logs a User or Agent into the LiveVox platform to create a Session ID which must be used in subsequent API requests. You can log in to LiveVox public APIs with Single Sign On (SSO) capability or without it depending on the site configuration.

Session permissions are updated every 5 minutes. This means that when you add/remove a Service to a User/Agent or add/remove an Agent Skill to a User/Agent etc. you'll either have to wait 5 minutes for those new permissions to take effect or create a new Session ID.

How to Use the Session:

Using a Session in the APIs (ex: Getting a List of Agents)

#Request (JSON)
GET /configuration/agents?count=5&client=4199&offset=0
Host: localhost.com
Content-Type: application/json
Accept: application/json
LV-Session: 3d408e7b-8afd-4f3a-8973-a7bc1a4deefd
LV-Access: xyz

#Response
200 OK
Content-Type: application/json

{
   "agent":    [
            {
         "id": 17243,
         "loginId": "ABC2323",
         "firstName": "DEVLIN",
         "lastName": "MCDOUGAL",
         "phone": "6786486419",
		 "active": true
      },
            {
         "id": 21211,
         "loginId": "CJL1111",
         "firstName": "CHRISTINE",
         "lastName": "LAJOIE",
         "phone": "6178498808",
	     "active": true
      },
            {
         "id": 21751,
         "loginId": "ARTHUR2",
         "firstName": "ARTHUR",
         "lastName": "MADDOX",
         "phone": "6142093064",
		 "active": false
      },
            {
         "id": 22131,
         "loginId": "JFC1222",
         "firstName": "JENNIFER",
         "lastName": "CESPEDES",
         "phone": "4803190744",
		 "active": true
      },
            {
         "id": 23017,
         "loginId": "TMP_CAVALRY",
         "firstName": "TODD",
         "lastName": "PHILLIPS",
         "phone": "9255954457",
		 "active": true
      }
   ],
   "next": "configuration/agents?count=5&client=4199&offset=5"
}

CODE

This Login method is different than the Logon method of the LiveVox Agent APIs, which is specifically to log the agent to the LiveVox Automatic Call Distributor (ACD). The Login method of the Session API is used to get a Session ID which is required to use all other API methods and provides your permissions.

For example, you want to check services an agent can log in to so they can successfully log in to that service. To check the service list, you would first use the Login request to generate a Session ID on behalf of the agent who has authenticated with the agent desktop and you could then use that Session ID to make the Get Service Details request.

Login With SSO

If the Single Sign On (SSO) feature is enabled for your site, you can log in to LiveVox public APIs by using the SSO login method.
The LiveVox public API allows you to log on using a third-party identity provider (IdP). Currently, the LiveVox Platform supports Okta and Azure. In future releases, the LiveVox Platform is planning to support other IdPs. For more information, see the Single Sign On Capability section from the Admin Guide.

You need to have your own IdP, because LiveVox does not provide an IdP.
If you plan to use the LiveVox public APIs, you are required to use the Open ID Connect (OIDC) protocol.

Obtaining the Token from IdP (Okta Sample)

Get a new OAuth2 token from the identity provider. For more information, see the Okta explanation at https://developer.okta.com/docs/guides/implement-grant-type/ropassword/main/#flow-specifics.

SSO Login

Method: POST session/login

Parameters:

Name	Type	Mandatory?	Description
LV-Access	UUID	Yes	API tracking token associated with the client.

Body:

Key or Attribute	Type	Mandatory?	Description
clientName	String	Yes	Name of LiveVox client on whose behalf the session is being created. This is not the Display Name of the client, but rather the Client Code as it appears in the Client editor screen in the LiveVox Portal GUI.
oauthAccessToken	JWT	Yes	The OAuth2 JWT access_token from the OIDC identity provider.
agent	Boolean	No	If set to `true,` the login request is for an agent. If not included in the request, it defaults to false meaning that the login request is for a user.

Response Code: 200 OK

Body:

Key or Attribute	Type	Mandatory?	Description
sessionId	String	Yes	The LiveVox Session ID to be used in subsequent API requests.
clientId	Integer (ID)	Yes	The ID of the client corresponding to the `clientName` provided in the login request.
userId	Integer (ID)	Yes	The internal ID of the LiveVox user or agent corresponding to the `userName` provided in the login request.
banner	String	No	Reserved for FedRAMP

Create a new LV API session for a LV User

#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json

{
  "clientName":"QAE_API17_TST2",
  "agent":false,
  "oauthAccessToken":"XYZ"
 }

 
#Response (JSON)
200 OK
Content-Type: application/json

{
  "sessionId":"2ffb6aa2-316a-4d12-8536-a2c559f2e727",
  "userId":165303,
  "clientId":93119
}

CODE

Login Without SSO

Description: If the SSO is not enabled for your site, you can log in to the LiveVox public APIs by using this method.

Method: POST session/login

Parameters:

None

Body:

Key or Attribute	Type	Mandatory?	Description
clientName	String	Yes	Name of LiveVox client on whose behalf the session is being created. This is not the "Display Name" of the client, but rather the "Client Code" as it appears in the Client Editor screen in the LiveVox Portal GUI.
userName	String	Yes	Name of LiveVox user or agent on whose behalf the session is being created. An agents `userName` is case-insensitive while a users `userName` is case-sensitive.
password	String	Yes	Password associated with the username
agent	Boolean	No	If set to `true,` the login request is for an agent. If not included in the request, it defaults to false meaning that the login request is for a user.

Response Code: 200 OK

Body:

Key or Attribute	Type	Mandatory?	Description
sessionId	String	Yes	LiveVox Session ID to be used in subsequent API requests.
clientId	Integer (ID)	Yes	The ID of the client corresponding to the clientName provided in the login request.
userId	Integer (ID)	Yes	The internal ID of the LiveVox user or agent corresponding to the userName provided in the login request.
daysUntilPasswordExpires	Integer	No	The number of days until the password expires for the user or agents.

If the session was not successfully created, then an error is returned. See Errors for more information.
If the LV user/agent's account is locked out for any reason (for example, if the user/agent has surpassed the allowable number of invalid login attempts), the user/agent is informed in the response that the account is locked.
If the LV user/agent's password has expired, the user/agent is informed in the response.

Create a new LV API session for a LV User

#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json

{"clientName": "CAVALRY",
"userName": "API12",
"password": "livevox1"}


 
#Response (JSON)
200 OK
Content-Type: application/json

{
   "sessionId": "95d895a9-7a84-4270-9ec8-8a5c9388625e",
   "userId": 119570,
   "clientId": 4199,
   "daysUntilPasswordExpires": 111
}

CODE

Create a new LV API session for an Agent

#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json

{"clientName": "CAVALRY",
"userName": "API12",
"password": "livevox1",
"agent": "true"}

#Response (JSON)
200 OK
Content-Type: application/json

{
   "sessionId": "3d408e7b-8afd-4f3a-8973-a7bc1a4deefd",
   "userId": 363545,
   "clientId": 4199,
   "daysUntilPasswordExpires": 10
}

CODE

Incorrect clientName or userName

#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json

{"clientName": "Demo",
"userName": "API4231",
"password": "livevox13254",
"agent": "true"}

#Response (JSON)
404 Not Found
Content-Type: application/json

CODE

Incorrect Password

#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json

{"clientName": "CAVALRY",
"userName": "API1",
"password": "livevox1234",
"agent": "true"}

#Response (JSON)
403 Forbidden
Content-Type: application/json
 
{
   "code": 400,
   "message": "Invalid Password"
}

CODE

Password has Expired

#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json

{"clientName": "CAVALRY",
"userName": "API1",
"password": "livevox1234",
"agent": "true"}

#Response (JSON)
403 Forbidden
Content-Type: application/json
 
{
   "code": 400,
   "message": "Stale Password"
}

CODE

Logout

Description: Logs out a particular session ID, thus ending that session.

Method: DELETE /session/logout/{session}

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory?	Description
session	sessionId	String	Yes	LiveVox API session ID that you want to log out

Body:

None

Response Code: 204 No Content

Body:

None

Close an open LV API session

#Request
DELETE /session/logout/a3104123-de21-4b74-8efc-8771fa4c8455
Host: localhost.com
Content-Type: application/json
Accept: application/json 

#Response
204 No Content

CODE

Errors

For more information, see the Errors section on the REST APIs page.

Top of Page

Download PDF

Session API

Introduction

LV-Session Header

Session Expiration

User Roles

API Methods

Session Management

Change Password

Is Session Valid

Login With SSO

Login Without SSO

Logout

Errors

Cookie Notice