====== REST Authentication Sequence ======
Using REST authentication someone else performs the authentication of the user. As a proof of successful authentication the user receives a token (an encrypted string) that she can give to the server to prove someone has authenticated her identity.

Once a REST authentication token has been received it shall be given to the wrtc object using [[ixnx:wrtc:js:api:wrtc:setresttoken|wrtc.setRESTtoken()]]. The token will then be sent to server upon request.

There are many ways you can obtain a REST authentication token, you are free to implement it any way you like. wrtc_kit.js contains a helper function [[ixnx:wrtc:js:api:wrtc:fetchresttoken|wrtc.fetchRESTtoken()]] that you can use to obtain one using HTTP GET, but it is merely an example of one possible implementation.

Most of the REST authentication token handling is carried out automatically by wrtc_kit. You just need to make sure you fetch a REST authentication token at the start and fetch a new one in your [[ixnx:wrtc:js:api:wrtc:onneedresttoken|wrtc.onNeedRESTtoken()]] function.

**When someone requests REST authentication from you the following happens:**

===== Prerequisite =====
Before you can use REST authentication you need to fetch a REST authentication token. Usually the code to fetch the initial token is carried out in [[ixnx:wrtc:js:api:wrtc:init|wrtc.init()]] and the received token is given to the wrtc object by calling [[ixnx:wrtc:js:api:wrtc:setresttoken|wrtc.setRESTtoken()]]. wrtc_kit.js contains a helper function [[ixnx:wrtc:js:api:wrtc:fetchresttoken|wrtc.fetchRESTtoken()]] that you can use to obtain a REST authentication token using HTTP GET, but it is merely an example of one possible implementation.

Once wrtc_kit got the REST authentication token it will take care of sending it to the server for authentication when necessary.

===== wrtc.onAuthenticateFailed() =====
If the server has not accepted your REST authentication token event function [[ixnx:wrtc:js:api:wrtc:onauthenticatefailed|wrtc.onAuthenticateFailed()]] will be called.

The code handling this event should alert the user of the login failure.

If authentication failed because of too old REST authentication token (validity time expired) [[ixnx:wrtc:js:api:wrtc:onauthenticatefailed|wrtc.onAuthenticateFailed()]] will report errorCode 423, "expired" and immediately after [[ixnx:wrtc:js:api:wrtc:onauthenticatefailed|wrtc.onAuthenticateFailed()]] it will call [[ixnx:wrtc:js:api:wrtc:onneedresttoken|wrtc.onNeedRESTtoken()]] to allow system fetch a new REST authentication token.

===== wrtc.onLoggedIn() =====
If the server has accepted your REST authentication token event function [[ixnx:wrtc:js:api:wrtc:onloggedin|wrtc.onLoggedIn()]] will be called instead.

The code handling this event should notify the user she has been logged in.

===== wrtc.onNeedRESTtoken() =====
REST authentication tokens usually have an expiration time, after which the token is no longer valid. Before your current REST token's validation time expires event function [[ixnx:wrtc:js:api:wrtc:onneedresttoken|wrtc.onNeedRESTtoken()]] will be called allowing you to fetch a new REST authentication token before the old one expires.

After you have fetched the new REST authentication token you give it to the wrtc object by calling [[ixnx:wrtc:js:api:wrtc:setresttoken|wrtc.setRESTtoken()]].

====== Example ======
  function wrtc.init() {
    token = wrtc.fetchRESTtoken("company.com/token");
    if (token)
      wrtc.setRESTtoken(token);
  }
  
  wrtc.onAuthenticateFailed = function(obj, err) {
    window.alert("Authentication failed: " + err.errorCode + ": " + err.errorMsg);
  }
  
  wrtc.onLoggedIn = function(arg) {
    if (arg.addressName) {
      window.alert("Logged in as " + arg.addressName + " - " + arg.displayName);
      wrtc.addressName = arg.addressName;
    }
    if (arg.displayName)
      wrtc.displayName = arg.displayName;
  }
  
  wrtc.onNeedRESTtoken(token) {
    wrtc.fetchRESTtoken("company.com/token", function(newtoken){wrtc.setRESTtoken(newtoken); wrtc.changeCredentials()});
  }

The above code example is all is needed for full REST token authentication implementation. Let us go it through step by step:
  * [[ixnx:wrtc:js:api:wrtc:init|wrtc.init()]] fetches when page has been loaded a REST authentication token using a synchronous HTTP GET generated by [[ixnx:wrtc:js:api:wrtc:fetchresttoken|wrtc.fetchRESTtoken()]] (the code waits until token is received). If a valid token has been obtained it is passed to wrtc object using [[ixnx:wrtc:js:api:wrtc:setresttoken|wrtc.setRESTtoken()]]. You are free to fetch REST authentication token in any way you like as long as you call [[ixnx:wrtc:js:api:wrtc:setresttoken|wrtc.setRESTtoken()]] with the obtained token. The HTTP GET method is based on that user needs to log in to company.com server to be able to access page company.com/token that contains the autogenerated REST authentication token. Only if she successfully logged in to company.com can she obtain the REST authentication token thus the fact that she has a token proves that company.com server has authenticated her.
  * Please note that there is no [[ixnx:wrtc:js:api:wrtc:onauthenticate|wrtc.onAuthenticate()]] function defined as the default one that simply calls [[ixnx:wrtc:js:api:line:authenticate|line.authenticate()]] is sufficient.
  * [[ixnx:wrtc:js:api:wrtc:onauthenticatefailed|wrtc.onAuthenticateFailed()]] notifies user about the authentication failure but does not need to do anything more. If the rest token is too old [[ixnx:wrtc:js:api:wrtc:onneedresttoken|wrtc.onNeedRESTtoken()]] will be called by wrtc_kit anyway. If the token is wrong fetching a new one will not make it any better.
  * [[ixnx:wrtc:js:api:wrtc:onloggedin|wrtc.onLoggedIn()]] sets [[ixnx:wrtc:js:api:wrtc:addressname|wrtc.addressName]] and [[ixnx:wrtc:js:api:wrtc:displayname|wrtc.displayName]] as those names might have been specified in the REST authentication token.
  * [[ixnx:wrtc:js:api:wrtc:onneedresttoken|wrtc.onNeedRESTtoken()]] occurs when current REST authentication token is getting too old. Then a new REST authentication token should be fetched. In this example the new token is fetched using an asynchronous HTTP GET generated by [[ixnx:wrtc:js:api:wrtc:fetchresttoken|wrtc.fetchRESTtoken()]]. Program execution continues while new REST authentication token is fetched. Once fetch is finished the callback is called that [[ixnx:wrtc:js:api:wrtc:setresttoken|installs the new REST authentication token]], and [[ixnx:wrtc:js:api:wrtc:changecredentials|requests a new user authentication]].

Please note the difference between the two [[ixnx:wrtc:js:api:wrtc:fetchresttoken|wrtc.fetchRESTtoken()]] calls: the one in wrtc.init() is synchronous because wrtc_kit needs a REST authentication token before it can continue and log you in. The one in wrtc.onNeedRESTtoken() however is asynchronous as then you have plenty of time fetching a new token (you can continue using the old one while you do it) but program execution cannot be halted for several seconds while new REST authentication token is fetched.

You can also implement a fully working implementation without the wrtc.fetchRESTtoken() and wrtc.setRESTtoken() calls in wrtc.init(). In that case, the first authentication attempt will fail with error code 423, triggering a wrtc.onNeedRESTtoken() call that fetches a REST token and requests a new authentication. The second authentication will then (hopefully) succeed.