API Authentication

These parameters are optional for unauthenticated API access (in some cases, you may get additional results here), and mandatory for authenticated API access.

Acquiring API tokens

If you don't already have a set of identifier tokens, you will need to acquire them.

API target: https://amphibiandisease.org/api.php Method: POST


Parameter Value
action login
username The email of the user
password The password of the user


Please note that a "JSON string" is not an object, below. It is instead a string representing JSON that will have to be json_decode()d (PHP) or JSON.parse()d (JavaScript).

Key Detail
status true or false (boolean)
user JSON string of {'COOKIE_NAME':'USER_EMAIL'}
link JSON string of {'COOKIE_NAME':'USER_DB_UNQ_ID'}.
name JSON string of {'COOKIE_NAME':'USER_FIRST_NAME'}.
full_name JSON string of {'COOKIE_NAME':'USER_FULL_NAME'}.
js A JavaScript function to evaluate using js-cookie to set the cookies in-browser.
ip_given The IP from which these cookies are valid. Changing IP addresses will invalidate the cookies.
raw_auth The data from response.auth
raw_secret The data from response.secret
raw_uid The data from response.link
expires The expires parameter on the cookies.

Aside: TOTP

Important Note: If your user is configured to use Two-Factor authentication, you'll recieve a response like:

  "status": false,
  "user": "foo@bar.com",
  "encrypted_hash": "jU+3Yson68O6vluIAStEnBFOX87xT0dmnYLauKs+jM8=",
  "encrypted_secret": "jU+3Yson68O6vluIAStEnBFOX87xT0dmnYLauKs+jM8=",
  "encrypted_password": "%2BaHg3NELhMcD%2FKUXrjAnXPu8xA4evKS0Ew8%2F%2Bv9Nxtk%3D",
  "human_error": "Please enter the code generated by the authenticator application on your device for foo@bar.com.",
  "error": false,
  "totp": true

Which you can test for by checking

# CoffeeScript
$.post endpointUrl, args, "json"
.done (response) ->
  if response.status is false and response.totp is true
    # We need to handle the user's TOTP

When you re-reply, send

Parameter Value
action login
username The email of the user
password The previous response's response.encrypted_password value
totp The TOTP value

Only once you've done that, will you get a response as above.

Sending API tokens

Assuming you're accessing the return in JavaScript and have named the variable response:

Parameter Value Meaning Key from Acquired Tokens
hash Verification value of user secret and server secret response.raw_auth
secret One of two parts of a secret session identiifer response.raw_secret
dblink Unique server ID for user; UserID equivalent response.raw_uid

For any authenticated/psuedoauthenticated request, these parameters can be sent as extra parameters to validate a login session. The cookie key pairs may also be sent in the header of the POST, rather than these raw cookie values.