Authorization Token

All agent side requests to the Presence Service carry an Authorization Token which can be obtained from the Glance Authorization Web Service. Glance uses the JSON Web Token (JWT) standard for creating, signing, and verifying authorization tokens.

A valid JWT:

  • Guarantees that the agent has been authenticated by Glance.

  • Indicates the specific privileges that the agent has.

If an agent is a member of multiple groups, bear in mind that the token is always group specific. To carry out an API operation in a particular group, the agent needs an Authorization Token for that specific group.

Warning

Authorization is resource intensive. To prevent performance problems, reauthorize only when the previously issued token expires. See the Presence Security Whitepaper for additional information on the Authorization Token.

Glance Authorization Web Service

An authorization token may be obtained server side using the Glance Authorization Service SOAP or REST API.

All credential properties are optional, but one of the following must be specified:

  • username and password
  • username and g4scredentials
  • username and loginkey
  • gssnid
  • partnerid, partneruserid, loginkey

Providing the Authorization Token to the GLANCE JavaScript APIs

The Authorization Token may be specified in metadata by adding the HTML attribute:

data-authtoken="[authorizationtoken]" to the cobrowse script tag as follows:

<script id="glance-cobrowse" data-authtoken="<authorization token>"...

The Authorization Token must appear on every page which makes API calls that require a token.

Alternatively, you can call GLANCE.Authorization.setToken(), documented below.

GLANCE.Authorization Javascript API

Glance also provides a JavaScript API for obtaining an Authorization Token. Refer to the Presence Agent Script documentation for more information on the presence agent script and how to include the presence agent API on your page.

GLANCE.Authorization.authorize(params)

This method invokes the Glance Authorization Web Service to obtain an Authorization Token.

params object:

{
  ws: "www.glance.net", //optional, defaults to www.glance.net
  service: "presence",
  groupid: 12345, // Numeric group id.
  site:  ["staging"|"production"] // Group settings to use for creating the authorization token. Defaults to "production".
  credentials: {
    username: "abc.glance.net", // Glance account username
    password: "password", // Glance account password
    gssnid: "", // Glance website login session id
    partnerid: 12345, // Partner id, usually same as groupid
    partneruserid: "", // Partner user id
    loginkey: "", // Login key signed with secret api key (*See additional login key documentation below),
    g4scredentials: // Glance for Salesforce credentials (*See additional login key documentation below)
  },
  duration: 20, //duration of the authorization token in minutes, 1-120
  onsuccess: function() {...}, // called if Authorization succeeds
  onfail: function(reason) {...} // called if Authorization fails
};

*Additional login key documentation is available here.

All credential properties are optional, but one of the following must be specified:

  • username and password
  • username and g4scredentials
  • username and loginkey
  • gssnid
  • partnerid, partneruserid, loginkey

A reason code is passed to the callback function on failure.

When authorizing client-side using the GLANCE.Authorization API, Glance caches the authorization token in local storage and reuses it; subsequent calls to GLANCE.Authorization.authorize() will call onsuccess() immediately. To force a new token to be obtained, call clearToken() first.

GLANCE.Authorization.setToken(token)

Use setToken if the authorization token is obtained server side and is passed via JavaScript.

GLANCE.Authorization.clearToken()

Clears the token, which may have been cached in local storage.