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 AttributeTypeMandatory?Description
clientNameStringYesName of LiveVox Client to which the User or Agent belongs.
userNameStringYesName of the LiveVox User or Agent who wants to change his password.
passwordStringYesCurrent password of the LiveVox User or Agent.
newPasswordStringYesNew 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.
agentBooleanNo

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 NameVariable NameTypeMandatoryDescription
sessionsessionIdStringYesID 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

Login

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:

NameTypeMandatory?Description
LV-AccessUUIDYesAPI tracking token associated with the client.

Body:

Key or AttributeTypeMandatory?Description
clientNameStringYesName 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.
oauthAccessTokenJWTYesThe OAuth2 JWT access_token from the OIDC identity provider.
agentBooleanNo

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 AttributeTypeMandatory?Description
sessionIdStringYesThe LiveVox Session ID to be used in subsequent API requests.
clientIdInteger (ID)YesThe ID of the client corresponding to the clientName provided in the login request.
userIdInteger (ID)YesThe internal ID of the LiveVox user or agent corresponding to the userName provided in the login request.
bannerStringNoReserved 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 AttributeTypeMandatory?Description
clientNameStringYesName 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.
userNameStringYes

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.

passwordStringYesPassword associated with the username
agentBooleanNo

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 AttributeTypeMandatory?Description
sessionIdStringYesLiveVox Session ID to be used in subsequent API requests.
clientIdInteger (ID)YesThe ID of the client corresponding to the clientName provided in the login request.
userIdInteger (ID)YesThe internal ID of the LiveVox user or agent corresponding to the userName provided in the login request.
daysUntilPasswordExpiresIntegerNoThe 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 NameVariable NameTypeMandatory?Description
sessionsessionIdStringYesLiveVox 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