====/api/auth====

===Usage===

Authenticates against the ARDI server to allow elevated function execution.

Note that you **must** call this function before calling any other ARDI function other than [[/api/connect]] when the server is not in guest mode.

Note that this documentation covers the //interactive// version of signing into ARDI. This lets a user sign in without sharing password details and allows them to use 3rd party services sign as Single Sign-In. 

If your application will work 'headless' or unattended, you should consider the [[api_auth_trad|traditional method]] of authentication.

===Flow===

The interactive authentication method requires multiple steps.

1) Call the **/api/auth** endpoint to get a redirection url \\
2) Open the redirection url in the users browser \\
3) Poll the **/api/auth** endpoint to get an auth token \\

===Details==

^Detail^Value^
|Group|Server|
|From Server Version|0.9.0|
|Permission|[[permission_guest|Public]]|
|Methods|GET or POST|

==Parameters==

^Parameter^Notes^Meaning^
|**code**|The unique sign-in attempt code (not required on the first call)|
|**format**|String (xml)|Either 'xml' or 'json'|

===Return Value===

This function returns either JSON or XML data. You will call it at least //twice// during the authentication process - once to **start** authentication, and at least one more time to **finish** it. 

===Examples===

==Initial Request==

First, we send an auth request without any code, username or password.

<code>
http://<servername>/s/<sitename>/api/auth?format=json
</code>

We get back the following...

<code javascript>
{
   "redirect": "https:\\localhost\s\empty\user\login?api=<interactive sign-in key>",
   "check":"\api\authcode=<interactive sign-in key>",
   "code":"<interactive sign-in key>"
}
</code>

The sign-in key you're given is **not** your API token. It's a unique ID to represent your sign-in attempt and is used as part of the authentication flow.

==Open Browser==

The browser is then opened and user taken to the URL provided in the **redirect** value.

==Poll For Response (Incomplete)==

Next, the application polls the authentication endpoint for success by sending a request to /api/auth with the 'code' parameter set.

<code>
http://<servername>/s/<sitename>/api/auth?format=json&code=<interactive sign-in key>
</code>

When the user has not yet entered their details, you'll get the following response...

<code javascript>
{
   "check":"/s/empty/api/auth?code=<interactive sign-in key>",
   "code":"<interactive sign-in key>",
   "message": "pending"
}
</code>

This result simply suggests trying again. If the user doesn't continue with authentication, the sign-in token will time-out and no longer be available - a 401 'Authentication Failed' response will be sent.

If the user successfully signs in, you'll be able to get your API key from the response.

<code javascript>
{
   "authcode":"<your api key>",
   "level":"admin",
   "message":"success"
}
</code>

Use the 'authcode' as your API key to sign future requests.