/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

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.

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

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

We get back the following…

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

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.

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=<interactive sign-in key>

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

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

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.