====== setRESTtoken() ======
wrtc.setRESTtoken() is used to set REST authentication token.

REST authentication is carried out by user being authenticated by third part that gives user a token. Wrtc_kit will then send this token to IXNX server to prove it has been authenticated.

There are different methods to obtain the REST authentication token. One using HTTP GET is provided for your convenience [[ixnx:wrtc:js:api:wrtc:fetchresttoken|wrtc.fetchRESTtoken()]]. You are however free to use whatever method you prefer to obtain the REST authentication token.

Once you have a fresh REST authentication token you must call wrtc.setRESTtoken() to give the token to the wrtc object.

Apart from storing the received REST authentication token, wrtc.setRESTtoken() also examines the unencrypted parts of the token and:
  * sets [[ixnx:wrtc:js:api:wrtc:addressname|wrtc.addressName]] if token contains a u= field
  * sets [[ixnx:wrtc:js:api:wrtc:displayname|wrtc.displayName]] if token contains a dname= field
  * returns REST token path (URL to fetch next REST token from) if token contains a p= field
  * starts a timer that will raise event [[ixnx:wrtc:js:api:event.newresttoken|wrtc.event.newRESTtoken]] after 75% of expiration time has passed if token contains an e= field

After wrtc.setRESTtoken() you need to call [[ixnx:wrtc:js:api:wrtc:changecredentials|wrtc.changeCredentials()]] to send the new token to IXNX server.

===== Arguments =====
wrtc.setRESTtoken(token)
  * token - the new REST authentication token

===== Returns =====
REST token path (URL to fetch next REST token from) if token contains a p= field, or undefined.

===== Also See =====
[[ixnx:wrtc:js:api:wrtc:fetchresttoken|wrtc.fetchRESTtoken()]]

[[ixnx:wrtc:js:api:line:authenticate|line.authenticate()]]