API use security

You can secure access to the API documentation and test page at exchange/api, by securing access to this exchange/api page.  Allow IP access to this page for only the users that you want to use the functions in this page. The page is also available to logged in System Administrators only, at System>Utilities>Information>API Methods.

The RefTracker API is available for use in developing custom interfaces, but is also used internally within RefTracker. 

Regarding internal use of the API:
The API methods called by ReftService check that the IP of the caller is the same as the IP of the RefTracker server.  This means any call to execute a RefTracker background process must come from the same server that RefTracker is running on.  Any call from outside the network running the RefTracker server, will be ignored.

The internal API web methods check either for a staff login, or that the session is an established RefTracker session if the method is used by client pages.  This means that any calls to these methods that are not from RefTracker will be ignored.

For any calls that breach these rules, the response is simply terminated – no information is returned to the caller, but the attempt is recorded in the warning log.

Regarding external use of the API (such as for custom interfaces, the RefChatter interface and the RefTracker widget):
All parameters associated with external use of the API are collected in a new 9.x Security group of parameters.

Unless these 9.x parameters are enabled, the associated API methods cannot be used. This is the default setting for newly created RefTracker systems.

If a 9.x parameter is enabled, that API method can be used. To securely use that method it is important that a key is set for it and that that key is used in every call to that API method. More information about enabling methods, setting keys and using them is provided in the 9 – Security parameters help page and the API documentation help page.

The RefTracker API also needs port 80 or 443 for SSL open in IIS if it is being accessed through firewall. To test if your RefTracker API is accessible externally try this URL in a browser external to your firewall:
{YourRefTrackerDomain}/exchange/api.asmx/requestForms

Further, the api.xml file in the config/settings directory is used to limit what domains the API can be used from.  Add the domain/s from which you want to use the API, between the <access> tags of the api.xml file, to allow access from domains other than your RefTracker system’s own domain (by default the API can only be used from the same domain as your RefTracker system).  For example, the RefTracker widget form works from its exchange/widget/example/methods.html test page because it is in the same directory as your RefTracker system, but it will not work from your corporate web pages, unless you add that domain to the api.xml file.

It is important that you set up the api.xml file if you are going to use the API (including use of the RefTracker widget form).

Whenever the RefTracker API is used through a browser (as it is for the Widget), it needs to comply with the CORS standard (Cross ORigin Security), and RefTracker does that via the api.xml file that can be used to limit what domains the API can be used from.
This api.xml file, accessible at System>Utilities>Administration utilities>File upload download and the config/setting directory, contains a record for each API method.
If the access for a method is set to * this means that any domain will be allowed from a CORS point of view (i.e. Cross ORigin Security in the browser).
If the access is set to a domain it will restrict use (in a browser) to that domain or list of domains – for example, to restrict to the abc company’s test sub domain you would set
<access>http://test.abc.com</access>
Note however that any API method must be enabled in the 9.x parameters for any of this to be relevant. Unless the method is enabled in the appropriate 9.x parameter, the method cannot be used anywhere.
By default the api.xml file is set to allow ALL access except QuickQuestion, so as soon as you set a 9.x Parameter on, that access is from browsers for all domains.  We highly recommend that you use an <access> setting like the one shown above to restrict use of the widget to the domain/s of the web page/s into which you have inserted your API use only.

If the domain that is making the request to RefTracker is not allowed the browser will not be able to perform the AJAX call.  To obtain diagnostics when testing this, use the Browser tools console to view error messages. 

This api.xml file does not secure the web method as such (the 9.x parameters do that) – it instructs the browser as to which domains are allowed to call the server via an AJAX call from the browser.

It does not prevent a call to the web method on the server from some other sources.

As an example here is how it should be set for the RefTracker widget that uses the API QuickQuestion method.

Example of security for the API – securing the RefTracker widget

1.  As described in the Widget documentation:
Parameter 9.50 must be enabled the Widget to be used, and the APIkey entered in the qq file.
2.  Also, as described in the widget documentation, the api.xml file needs to be set to control what domains the API can be used from. 
Whenever the RefTracker API is used through a browser (as it is for the Widget), it needs to comply with the CORS standard (Cross ORigin Security), and RefTracker does that via a the api.xml file that can be used to limit what domains the API can be used from. 

By default the api.xml file is set to allow ALL access except QuickQuestion, so as soon as you set Parameter 0.81 to Yes, all other types of API access are allowed from browsers for all domains.  We highly recommend that you use an <access> setting like the one shown above to restrict use of the widget to the domain/s of the web page/s into which you have inserted your API use only.

If the domain that is making the request to RefTracker is not allowed the browser will not be able to perform the AJAX call.  T