====== fetchRESTtoken ======
wrtc.fetchRESTtoken() is used to load a REST authentication token using HTTP GET.

wrtc.fetchRESTtoken() sends an HTTP GET request to the specified web URL and returns contents of retrieved web page if it contains a REST authentication token. The remote web server should thus be configured to just return the REST authentication token at that URL, not a webpage. By forcing user to log in to access the webpage authentication will then be carried out by the web server and the fetched token is a proof of the successful authentication. (Could not log in = can not fetch token.)

<WRAP center round important 100%>
You are free to fetch your REST authentication token in any way you like, you do not have to use wrtc.fetchRESTtoken().
</WRAP>

===== Arguments =====
wrtc.fetchRESTtoken(url, callback)
  * url - web URL to fetch REST authentication token from
  * callback - (optional) function to call once REST authentication token has been fetched

===== Returns =====
==== Synchronous operation ====
If you do not specify a callback function wrtc.fetchRESTtoken() will be executed synchronously: program execution is halted until web server has responded. wrtc.fetchRESTtoken() will then return:
  * **string** containing REST authentication token if it has been fetched correctly
  * **false**: the fetched webpage did not contain a valid REST authentication token
  * **null**: specified web page could not be loaded
The difference between false and null return values is that false indicates wrong page format, there is no need to retry, while null indicates page load problems, you could try to reload page again.

<WRAP center round important 100%>
While synchronous operation may be easier to code you are recommended to call wrtc.fetchRESTtoken() asynchronously to avoid lengthy stops (up to 30 secs!) in program execution.
</WRAP>

==== Asynchronous operation ====
By specifying a callback function wrtc.fetchRESTtoken() will send the page request to the web server but will then return immediately (with null as return value).

When web server responds with a valid REST authentication token the callback function will be called with the received new token as argument. Callback function can then give token to wrtc:
  wrtc.fetchRESTtoken("company.com/token", function(newtoken){wrtc.setRESTtoken(newtoken); wrtc.changeCredentials()});

===== Also See =====
[[ixnx:wrtc:js:api:wrtc:setresttoken|wrtc.setRESTtoken()]]