====== line.authenticate() ======
line.authenticate() performs your authentication towards a server requesting it.

Usually you do not need to call line.authenticate() manually - it is called by wrtc_kit automatically when needed. In some advanced scenarios with different logins to different realms you may need to write your own [[ixnx:wrtc:js:api:wrtc:onauthenticate|wrtc.onAuthenticate()]] that calls line.authenticate()

line.authenticate() can perform digest and REST token authentications. It is the server requesting the authentication that decides which authentication method to use.

===== Arguments =====
Basic implementations call line.authenticate() without any arguments but more advanced implementations may supply arguments.

When calling line.authenticate() without arguments it will use the object's [[ixnx:wrtc:js:api:wrtc:sipauthname|wrtc.sipAuthName]], [[ixnx:wrtc:js:api:wrtc:sippassword|wrtc.sipPassword]] and [[ixnx:wrtc:js:api:wrtc:sipha1|wrtc.sipHa1]] properties to perform digest authentication with. REST token authentications will instead use the REST token supplied to latest [[ixnx:wrtc:js:api:wrtc:setresttoken|wrtc.setRESTtoken()]] call.

Advanced implementations can also supply their own username and password that will override [[ixnx:wrtc:js:api:wrtc:sipauthname|wrtc.sipAuthName]] and [[ixnx:wrtc:js:api:wrtc:sippassword|wrtc.sipPassword]]:\\
line.authenticate(arg)
  * arg - (optional) JSON structure: {sipAuthName:..., sipPassword:..., sipHa1:..., restToken:...}
    * sipAuthName - (optional) SIP authentication name to use instead of [[ixnx:wrtc:js:api:wrtc:sipauthname|wrtc.sipAuthName]]
    * sipPassword - (optional) SIP password to use instead of [[ixnx:wrtc:js:api:wrtc:sippassword|wrtc.sipPassword]]
    * sipHa1 - (optional) SIP password hashsum to use instead of [[ixnx:wrtc:js:api:wrtc:sipha1|wrtc.sipHa1]]
    * restToken - (optional) REST token to use instead of the one supplied to latest [[ixnx:wrtc:js:api:wrtc:setresttoken|wrtc.setRESTtoken()]]

===== Returns =====
True if authentication could be carried out (no indication of authentication success, only for attempt), or false if authentication could not be carried out (due to eg missing indata).

===== Also See =====
[[ixnx:wrtc:js:api:wrtc:onauthenticate|wrtc.onAuthenticate()]]