Authentication

This application uses a JSON Web Token(JWT) to track and authenticate each user and API request. Most routes require a valid JWT in the Authorization header as Bearer [JWT]. This guide provides explanations and details on each related route related to getting JWTs.

Getting a JWT token

Note: every user is considered either a "Teacher" or a "Student". Developers or Admins will sign in as teachers.

Route: /api/session/login

Method: POST
Authentication: This route requires no JWT.

Example request body:

    {
        email: "teacher@school.edu",
        password: "iLoveCats!!"
    }

If the user is found in our database and the password is correct, you'll be given a response like this:

    {
        status: 'ok',
        token: 'NA95PfGVmgzOXZrDEd7M6MzWj1gT5wLjJ3pnIH15AAvNqAhPJ7fS0ODN6mBz', // this is your JWT Token, be sure to save it!
        teacher: {
            "_id": "5bdf58e7b9bfebb9ee3848d9",
            "name": "George Burdell",
            "email": "teacher@school.edu",
            "teacher_id": "001",
            "createdAt": "2018-11-04T20:39:03.144Z",
            "updatedAt": "2018-11-29T02:22:47.737Z",
            "__v": 0
        }
    }

Otherwise, expect a response like this:

    {
        status: 'error',
        message: 'Your email / password combination is incorrect.'
    }

Registering

Well you're able to sign in now, but what about registering in the first place? That would look something like this:

Route: /api/session/register

Method: POST
Authentication: This route requires no JWT.

Example request body:

    {
        name: 'Jane Doe',
        email: 'teacher@school.edu',
        password: 'iLoveCats!!'
    }

If the teacher is not already found in the database and everything checks out, expect a response like this:

    {
        status: 'ok',
        teacher: {
            "_id": "5bdf58e7b9bfebb9ee3848d9",
            "name": "Jane Doe",
            "email": 'teacher@school.edu',
            "teacher_id": "003",
            "createdAt": "2018-11-04T20:39:03.144Z",
            "updatedAt": "2018-11-29T02:22:47.737Z",
            "__v": 0
        },
        token: 'NA95PfGVmgzOXZrDEd7M6MzWj1gT5wLjJ3pnIH15AAvNqAhPJ7fS0ODN6mBz' // Your JWT token
    }

Student Login

Route: /api/session/student

Method: POST
Authentication: This route requires no JWT

Example request body:

    {
        id: '001503' // The 6-digit conjoined teacher_id + student_id
    }

Example response body:

    {
        status: 'ok',
        token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjViYjE0OTVmNjMyNDBhZDUzNGQ0MGMzNyIsInR5cGUiOiJzdHVkZW50IiwiaWF0IjoxNTQzNTk5MTY3fQ.6kYl3oHfsW52WB4cSE9gUyaB4qIHMigHKaVo620J0y0',
        student: {
            "deleted": false,
            "_id": "5bb1495f63240ad534d40c37",
            "student_id": "109",
            "teacher": "5bdf58e7b9bfebb9ee3848d9",
            "createdAt": "2018-09-30T22:08:33.224Z",
            "updatedAt": "2018-09-30T22:08:33.224Z",
            "__v": 0
        }
    }

Note: students are created using the students API

Reset Teacher Password

This route changes the password for the logged in teacher.

Route: /api/session/resetpassword

Method: POST
Authentication: This route requires a Teacher JWT

Example request body:

    {
        password: "NewPassword", //The new password, must be at least 7 characters
        confirm_password: "NewPassword" // Same password again, no client side validation here!
    }

Example response body:

    {
        status: 'ok',
    }

Get Teacher Info

This route gets the information stored on the logged in teacher.

Route: /api/session/info

Method: GET Authentication: This route requires a Teacher JWT

Example request body:

    {
    }

Example response body:

    {
        status: 'ok',
        teacher: {
            name: "LoggedInTeachers Name",
            email: "teachersEmail@aol.com",
            teacher_id: "007", //Three digit teacher id as a string
            _id: "23234a344e9304f909b09c" // Internal id used for API calls
        }
    }

Get Student Info

This route gets the information stored on the logged in student.

Route: /api/session/studentinfo
Method: GET This route requires a Student JWT Example request body:

    {
    }

Example response body:

    {
        status: 'ok',
        teacher: {
            teacher: "398593284923a0099e0099d0", // Internal id of the Teacher this student is associated with
            student_id: "007", // Three digit student id as a string
            _id: "23234a344e9304f909b09c", // Internal id used for API calls
            deleted: false // True if this student has been deleted
        }
    }

Teacher forgot login

Did you as a teacher forget your password? Never fear! We implemented an email-based password recovery system. If you post an email to this route, the system will use the system's Gmail account brainyhearatale@gmail.com to send a password recovery email in the format: https://teacherportal.hearatale.com/api/session/forgotpassword?tid=' + teacher._id +'?pid=' + passwordResetModel._id

Route: /api/session/forgotpassword
Method: POST Example request body:

    {
        email: teacheremail@teaching.edu
    }

Example response body:

    {
        status: 'ok',
        message: 'Email was sent to teacheremail@teaching.edu'
    }

Route: /api/session/forgotpassword
Method: GET Example query:

    https://teacherportal.hearatale.com/api/session/forgotpassword?tid=' + teacher._id +'?pid=' + passwordResetModel._id

Example response body:

{
    status: 'ok',
    message: 'Your new password is: ' + DEFAULT_NEW_PASSWORD
}

(the DEFAULT_NEW_PASSWORD is 'youshouldreallychangethis')