Authentication
Login Procedures
Please remember to use the dev server (fireroad-dev.mit.edu) for all local testing, and only use the production server (fireroad.mit.edu) for your production application. Use of the production server requires prior approval by the FireRoad team (see "Approval" below). The workflow for logging into the FireRoad server as a web application is as follows:- Your site sends the user to /login, with an optional query parameter sem indicating the user's current semester, and required query parameter redirect indicating the redirect URL after login. For production, this redirect URL needs to be registered with FireRoad before use.
- The FireRoad server handles login through Touchstone, creates a FireRoad account if necessary, then sends the user back to your redirect URL, passing a query parameter code
- The code is a string that can be used exactly once within 5 minutes of login to retrieve an access token. The application server does this by sending a request to /fetch_token, passing the query parameter code received in step 2.
- The FireRoad server validates the temporary code and sends the application server back a JSON web token (JWT) that can be used to authorize use of the API.
- The application server uses the JWT by including the Authorization header set to "Bearer <base-64 encoded token string>" in any request to the FireRoad server.
- Since the JWT may expire, the application server should check its validity by requesting the /verify endpoint with the Authorization header. If the token is expired or invalid, this endpoint will return 403, indicating that the user should log in again.
Approval
To use the FireRoad production server, you must contact the FireRoad development team with the following information:- The name and description of your service. The name will be displayed to users when asked to approve access to your application.
- A name and email address for the point of contact for the application.
- The permissions that your application needs to function correctly (specifying whether read or read/write access is needed). When FireRoad issues your application an access token, that token will only be usable for the permissions you specify.
Endpoints
/signup
Displays a user-facing page that specifies the conditions of allowing recommendations.
/login
Redirects to the OAuth page to log the user in. See "Login Procedures" for how to log in as a web client. Note: Web clients must include a redirect query parameter. Requests without a redirect parameter will be treated as coming from a native (mobile) app, and will transfer the token to the client in a way that is not secure outside of a native app.
/fetch_token (GET)
Takes a query parameter code and, if it is valid and unexpired, returns the associated access token. See "Login Procedures" above for more details.
/verify (GET)
Checks that the user is logged in, and if so, auto-increments the user's current semester and returns the new semester.
/user_info (GET)
(Requires authentication) Returns a JSON object containing information about the current user, including the following keys:
- academic_id: the user's institution email address
- current_semester: the user's current semester (numbered 0)
- name: the user's full name
- username the user's username on the FireRoad server (not human-readable)