System Settings API call

This API call offers an easier way to detect what functions is available to API clients.

Example using curl:

curl -H "Accept: application/json" https://liquidfiles.company.com/
{
  "message": "Please see the API documentation for instructions how to access",
  "settings": {
    "api_enabled": true,
    "api_web": {
      "enabled": true,
      "auth_url": "/session/api",
      "logout_url": "/session/api/logout",
      "saml_auth_url": "/saml/api",
      "saml_logout_url": "/saml/api/logout",
      "saml_authentication": "supported"
    }
  }
}

How to use

Again, the purpose for this call is to make it easier to implement API clients. The first check you can make when implementing the client is to see if the API has been enabled or disabled on this system globally with the api_enabled boolean value of true or false.

The rest of the settings has to do with implementation of the Web Based API authentication. The auth_url, auth_logout_url, saml_auth_url and saml_auth_logout_url are the relative login and logout URLs for the Web based API and Web base SAML API functions. But it may not be obvious what to use which one when.

Looking at the saml_authentication setting in the api_web response, you can use this setting to enable, disable or require SAML authentication from the client. If we use the Outlook plugin as an example, there's two buttons "Login" and "SSO Login". If saml_authentication is "unsupported", only the "Login" button is presented to the user. If saml_authentication is "supported", both "Login and "SSO Login" is presented and if saml_authentication is "required" then only the "SSO Login" button is presented to the user.

Continuing with this example, when a user clicks "Login", you would open up a browser window to the relative auth_url. If a user clicks "SSO Login", you would open up a browser window to the relative URL saml_auth_url.

If the user has logged in without SAML and logs out from the client, you will need to make a call to the relative logout_url URL and if the user has logged in with SAML you will need to make a call to the relative saml_logout_url URL.

Please see the Web Based API authentication documentation for more information.

Security Concerns

This section is for our security auditing friends that will no doubt look at this and think to themselves that "this is leaking information" — but it doesn't.

You can make any API call and if the API is disabled there will be a message if the API is disabled or not.

All the relative URLs are hard coded and the same on all systems.

You can easily check if saml authentication is supported by looking on the main login page. If the "SSO Login" button is visible, it means that SAML authentication is supported. If there's no "SSO Login" button it means that SAML authentication is unsupported, and if you get instantly redirected to the SAML server it means that SAML authentication is required.

So you can see that there's no information presented here that is not also available, without authentication, anyway. Making it available in a JSON API call just makes it easier to access when implementing API clients.