/api/auth

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 traditional method of authentication.

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|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=== The return value is an XML or JSON file that returns an authcode. This code is included with all future API requests as part of Signing Your Requests. ===Examples=== ==Initial Request== First, we send an auth request without any username or password. <code> http:<servername>/s/<sitename>/api/auth?format=json </code>

We get back the following…

{
   "redirect": "https:\\localhost\s\empty\user\login?api=f29f519a0bcb3b79dbc62c780e03c29f17612ceb2cfa07c540a5277677d9f488"],
    "check":["\api\authcode=f29f519a0bcb3b79dbc62c780e03c29f17612ceb2cfa07c540a5277677d9f488"],
   "code":"f29f519a0bcb3b79dbc62c780e03c29f17612ceb2cfa07c540a5277677d9f488"}

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

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

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

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

{
   "check":"/s/empty/api/auth?code=41ecbe95903ef6730ace68b212c79b77d1398e4e3e05150506944e6500bcd2a2",
   "code":"41ecbe95903ef6730ace68b212c79b77d1398e4e3e05150506944e6500bcd2a2"}

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.

{
   "authcode":"3bb25fbf754209e2633bed7ba7d9ff3e",
   "level":"admin",
   "message":"success"
}

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