Authentication

Authentication

All requests are authenticated with the ffauth_device_id and ffauth_secret URL query parameters

Getting a Token (Uses Web Browser)

First, you must visit your school instance online using a standard browser and log in as you would normally. Then make the request below in the same authenticated browser (you only need to change the URL).

Request

GET request to /Login/api/gettoken?ffauth_device_id={ Device ID }&ffauth_secret=&device_id={ Device ID }&app_id={ App ID }

The URL /login/login.aspx?prelogin={ Get Token Endpoint URL } can also be used if not already logged in. This will ask the user to login, then redirect them to the token endpoint

• Host - String - The host/base endpoint of the instance, typically something like https://school.fireflycloud.net
• Device ID - String - A random string which is used to identify the device. It should be unique
• App ID - String - A string which is used to identify the app in the Account Settings/Apps tab on the main webpage dashboard in order to revoke access. The App ID for the default Student Planner for iOS is ipad_tasks

Response (XML)

<?xml version="1.0" encoding="utf-8"?>
<token>
    <secret>
    {{ Secret }
    </secret>
    <user demo="no" product_survey="no" contact_signup="yes" local="no" username="{{ Username }}" fullname="{{ Full Name }}" email="{{ Email }}" guid="{{ GUID }}" role="{{ Role }}" heap_id="{{ Heap ID }}" heap_handle="{{ Heap Handle }}" heap_role="student" logouturl="logout" abdicate="no" abdicateDashboard="yes">
        <classes>
            <class guid="{{ Class GUID }}" name="{{ Class Name }}" subject="{{ Class Subject }}"/>
			<class guid="{{ Class GUID }}" name="{{ Class Name }}" subject="{{ Class Subject }}"/>
        </classes>
    </user>
    <installation version="{{ Installation Version }}" integer-version="{{ Installation Integer Version }}" mode="{{ Installation Mode }}" id="{{ Installation ID }}"/>
    <browser dhtml="yes">
        <product>Firefox</product>
        <platform>WinNT</platform>
        <version major="1" minor="0"/>
    </browser>
    <datetime day="01" dayname="Monday" month="01" monthname="January" year="2000" time="01:23" time12h="01:23 AM" exacttime="01:23:45" rfc1123="Mon, 01 Jan 2000 01:23:45 GMT"/>
</token>

• Secret - String - The secret for the token
• Username - String - The username of the user
• Full Name - String - The full name of the user
• Email - String - The email of the user
• GUID - String - The GUID of the user
• Role - String - The role of the user. Typically student
• Heap ID - Integer - The ID of the user across Firefly
• Heap Handle - String - The handle of the user across Firefly. Typically {{ username }}@{{ host }}
• Class GUID - String - The GUID of the class
• Class Name - String - The name of the class. Typically the set
• Class Subject - String - The subject of the class.
• Installation Version - String - The version of the instance. (x.x.x)
• Installation Integer Version - Integer - The version of the instance in an integer form. (xxxxx)
• Installation Mode - String - The mode of the instance. Typically Firefly 6 is enabled
• Installation ID - Integer - The ID of the instance across Firefly

Verify Token

Note - Using the same browser as the one that obtained the token returns an invalid response. If this doesn't work, try using a private window or a different browser.

Request

GET request to /Login/api/verifytoken?ffauth_device_id={{ Device ID }}&ffauth_secret={{ Secret }}

• Device ID - String - The string used to identify the request
• Secret - String - The secret obtained to authenticate the request

Headers

• User-Agent: Any string

Response (JSON)

Invalid Token

{
  "valid": false,
  "displayTitle": "You have been logged out",
  "displayMessage": "Invalid Login"
}

Valid Token

{
  "valid": true,
}

Delete Token

Request

GET request to /login/api/deletetoken?ffauth_device_id={{ Device ID }}&ffauth_secret={{ Secret }}&app_id={{ App ID }}

• Device ID - String - The string used to identify the request
• Secret - String - The secret obtained to authenticate the request
• App ID - String - The app ID which was submitted when the token was generated (also found in the Account Settings/Apps tab on the main webpage dashboard)

Headers

• User-Agent: Any string

Response

Success

OK

Note that this will always be the response as long as the credentials are correct. If the App ID didn't match, the token will still not be deleted.