How To Enable External API Access

FogBugz Plugin API > Enable External API Access

The FogBugz XML API allows external applications to interface with FogBugz. The XML API uses tokens to authenticate the user after initial logon. The plugin CAuthenticationAPI includes methods CreateLogOnToken() and DestroyLogOnToken(String sToken) to allow plugins to create and destroy (invalidate) these tokens.

Purpose and Features

This feature makes it possible to buld additional externally-accessible APIs (by implementing the IPluginRawPageDisplay interface) as plugin pages. An external app can then hit those pages and to be authenticated as a particular user using an authentication token shared with the XML API.

When the external app accesses the API you've built in your plugin raw page:

1. You can pass "token={token}" in the request URL to it (or any plugin page) and be authenticated as that user for the duration of the request.
2. You can pass sPluginId to any plugin page in place of ixPlugin. This allows your external app to work without having to know the ixPlugin. The ixPlugin is generated based on the order plugin is installed.
3. When passing parameter values to plugin pages via the request URLn plugin pages, you can omit the Plugin ID from the prefix. For example, use "P_myfieldname" instead of "P15_myfieldname" (for a plugin with ID 15).

All of the above are independent, so using "P_myfieldname" instead of "P15_myfieldname" doesn't mean that you must use sPluginId and not ixPlugin.

Example Usage

An external application could authenticate a user via the XML API by accessing this URL:

http://[FogBugz URL]/api.asp?cmd=logon&email=email&password=password

...or your username works as well in the case that your email addresses are not unique among your users (i.e. if addresses can be shared):

http://[FogBugz URL]/api.asp?cmd=logon&email=username&password=password

This request would return a logon token string. This token can then be used by the application when it accesses a plugin's raw page to make an API call, in this case, passing "runreport" as the value of a parameter, "cmd":

http://[FogBugz URL]/default.asp?pg=pgPluginRaw&ixPlugin=15&P15_cmd=runreport&token=token

The approach above would require the external application to know the plugin's ixPlugin (15 above). Because this key is determined by the order plugins are installed in FogBugz, a better approach is to access the plugin pages by the plugin ID string, sPlugin=pluginID, and prefixing parameters with "P_" (only work on plugin pages):

http://[FogBugz URL]/default.asp?pg=pgPluginRaw&sPlugin=customreport@mycompany.com&P_cmd=runreport&token=token

For more information on the XML API, see the online documentation.