The Basics

cmd=logon

Parameters
Takes either email AND password (email can be either email address or full name, passed in as email either way) OR token (alone)
Example
https://kakapo.fogbugz.com/api.asp?cmd=logon&email=elinor@kakapo.fogbugz.com&password=kakapo1234
Returns
A token, to be used for other API requests
cmd=logoff

Parameters
Takes only token.
Example
https://kakapo.fogbugz.com/api.asp?cmd=logoff&token=9o2atgqi41642331c5f6lo5c37u1ec
Returns
Empty Response

Logging on Through The API (cmd=logon)

In order to log on, you must generate an API token. You can do that through the API by providing an email address (or full name, just like FogBugz sign-in) and password in the logon command. You can also generate an API token through the user interface. Users with two factor authentication enabled cannot generate an API token through the API – the only way for a user with 2FA enabled to log on is to generate a token through the FogBugz user interface.

Email and Password

URL
https://kakapo.fogbugz.com/api.asp?cmd=logon&email=elinor@kakapo.com&password=kakapo1234
fogbugz.py
S_FOGBUGZ_URL   = 'https://kakapo.fogbugz.com/'
S_EMAIL         = 'elinor@kakapo.com'
S_PASSWORD      = 'kakapo1234'

fb = FogBugz(S_FOGBUGZ_URL)
fb.logon(S_EMAIL, S_PASSWORD)

Full Name and Password

It’s also possible to log on using a users full name. In this example, our user Elinor Bennet, is using her full name (url escaped) rather than her email address, but is still passing into the email parameter of the API call.

URL
https://kakapo.fogbugz.com/api.asp?cmd=logon&email=Elinor%20Bennett&password=kakapo1234
fogbugz.py
S_FOGBUGZ_URL   = 'https://kakapo.fogbugz.com/'
S_FULL_NAME         = 'Elinor Bennett'
S_PASSWORD      = 'kakapo1234'

fb = FogBugz(S_FOGBUGZ_URL)
fb.logon(S_FULL_NAME, S_PASSWORD)

Possible Responses

Failed Logon

Your email or password doesn’t match, 2FA might be turned on, etc. This is the equivalent of a failed attempt to log in through the interface.

XML
<response>
  <error code="1">Error Message To Show User</error>
</response>
Successful Logon

You get back an opaque string token which you will use for all subsequent requests. This token will persist until you execute a logoff command.

XML
<response>
  <token>24dsg34lok43un23</token>
</response>

We encourage you to reuse your tokens rather than issue repeated logon commands. (See below.) Your tokens do not expire – they’ll be good for the life of your FogBugz account.

Ambiguous Logon

There is more than one FogBugz user with that email address.  FogBugz will supply you with a list of full names; you must provide the appropriate full name to log on.

XML
<response>
  <error code="2">Ambiguous Logon</error>
  <people>
    <person>Elinor Bennett</person>
    <person>Lydia Dashwood</person>
  </people>
</response>

If, for example, you got that response, you would prompt the user with a combo box to choose if they are Elinor Bennett or Lydia Dashwood. If she’s Elinor, she would try logging on again with this URL:

https://kakapo.fogbugz.com/api.asp?cmd=logon&email=Elinor%20Bennett&password=kakapo1234

Using an Existing API Token

URL

To check the validity of an existing token, pass the token to the logon command in URL of your browser:

https://kakapo.fogbugz.com/api.asp?cmd=logon&token=9o2atgqi41642331c5f6lo5c37u1ec

fogbugz.py

To use an existing token using fogbugz.py, include the following as part of your script.

S_FOGBUGZ_URL   = 'https://kakapo.fogbugz.com/'
TOKEN = '9o2atgqi41642331c5f6lo5c37u1ec'
fb = FogBugz(S_FOGBUGZ_URL, TOKEN)

curl

The XML endpoint:

curl -X POST -d cmd=login -d token=9o2atgqi41642331c5f6lo5c37u1ec https://kakapo.fogbugz.com/api.asp

The JSON endpoint:

curl -X POST -H 'Content-Type: application/json' -d '{"cmd":"logon", "token":"9o2atgqi41642331c5f6lo5c37u1ec"}' https://kakapo.fogbugz.com/f/api/0/jsonapi

If your token is valid, you’ll receive:

XML
<response>
  <token>[your_token]</token>
</response>
JSON
{
  "data": { "token": "[your_token]" },
  "errors" : [],
  ...
  "errorCode": null
}

If your token is invalid, you’ll receive:

XML

<response>
  <error code="3">Not logged in</error>
</response>
JSON
{
  "data": { },
  "errors" : [ {"message": "Error 3: Not logged in", "detail": null, "code": "3" } ],
  ...
  "errorCode": 400
}

Logging Off (cmd=logoff)

Logging off is not necessary, and we encourage reusing tokens. If you’d like to expire a token, you can do so by entering the following into the URL bar of your browser.

https://kakapo.fogbugz.com/api.asp?cmd=logoff&token=9o2atgqi41642331c5f6lo5c37u1ec