Skip to content

HATS Auth API Specification

Notes

For any protected route, if the access token included in the request header is expired the backend will return a 401 with the following text indicating that a refresh is necessary: 

1
"Given access token is expired or invalid"

Common Headers

For any request with a body it is assumed that this header exists: 

1
Content-Type: application/json

Access Token Composition

  • userId: the ID of the authenticated user
  • privilegeLevel: the user's privilege level
  • ADMIN
  • OFFICER
  • VOLUNTEER
1
2
3
4
{
  "userId": 1,
  "privilegeLevel": "ADMIN"
}

Unprotected Routes

These routes are called by a user that is not yet authenticated.

User Login

Used to authenticate the given user.

POST request to /api/v1/user/login with body: - email: the user's email - password: the user's password

1
2
3
4
{
    "email" : "admin@email.com",
    "password" : "secure"
}

Responses:

201 Created: the email / password combination is valid; includes distinct access and refresh tokens for the given user: 

1
2
3
4
{
  "accessToken"  : "JWT_ACCESS_TOKEN",
  "refreshToken" : "JWT_REFRESH_TOKEN"
}

400 Bad Request: the given JSON request is malformed

401 Unauthorized: the email / password combination is invalid

User Login Refresh

Used for getting a new access token.

POST request to /api/v1/user/login/refresh with header: 

1
X-Refresh-Token: JWT_REFRESH_TOKEN

Responses:

201 Created: the refresh token is valid and has not yet expired; response includes a new unique access token: 

1
2
3
{
  "accessToken" : "JWT_ACCESS_TOKEN"
}

401 Unauthorized: the refresh token is invalid

User Logout

Used for logging the given user out.

DELETE request to /api/v1/user/login with headers: 

1
2
X-Access-Token : JWT_ACCESS_TOKEN
X-Refresh-Token : JWT_REFRESH_TOKEN

Responses:

204 No Content: logout successful

User Signup

Used for signing up a new user.

POST request to /api/v1/user/signup with body:

  • email: the user's email
  • password: the user's password
    • Requires 8-20 characters with at least one lowercase, one uppercase, one number, one special character
  • firstName: the user's first name
  • lastName: the user's last name
  • privilegeLevel: the user's privilege level
    • ADMIN
    • OFFICER
    • VOLUNTEER
  • country: the user's country:
    • UNITED_STATES
    • ANTIGUA_AND_BARBUDA
    • DOMINICA
    • GRENADA
    • ST_KITTS_AND_NEVIS
    • ST_LUCIA
    • ST_VINCENT_AND_THE_GRENADINES 
      1
2
3
4
5
6
7
8
      {
  "email" : "admin@email.com",
  "password" : "secure",
  "firstName" : "John",
  "lastName" : "Doe",
  "country": "UNITED_STATES",
  "privilegeLevel": "ADMIN"
}

Responses:

201 Created: the username and email are still available, and an account has been successfully created 

1
2
3
4
{
  "accessToken"  : "JWT_ACCESS_TOKEN",
  "refreshToken" : "JWT_REFRESH_TOKEN"
}

400 Bad Request: malformed request body

409 Conflict: the given email or username is already in use 

1
"Error creating new user, given email %s already used"

User Forgot Password Request

Used to send a reset password email to a user if they have forgotten their password.

POST request to /api/v1/user/forgot_password/request with body: 

1
2
3
{
  "email": "admin@email.com"
}

Responses:

200 OK: the email was sent to the user successfully

400 Bad Request: the given email is not associated with any user account

User Forgot Password Reset

Used to reset a user's password after they have requested a forget password link.

POST request to /api/v1/user/forgot_password/reset with body: 

1
2
3
4
{
  "secretKey": "SECRET_KEY",
  "newPassword": "secure123"
}

The secret key should be determined by the frontend link that the user clicked from their email.

Responses:

200 OK: the user's identity was confirmed and the password was changed successfully

400 Bad Request: the new password that was given is an invalid password

401 Unauthorized: the given secret key is invalid and does not refer to an account or was created too long ago to be valid

User Email Verification

Used for confirming an account's email.

GET request to /api/v1/user/verify/:secret_key with path parameters:

  • secret_key: is a secret key randomly generated by the backend and sent to the user by email.

Responses:

200 OK: the user's secret key has been verified

401 Unauthorized: the secret key is invalid or expired

Protected Routes

These routes are called by an authenticated user. These routes can only be called with a valid access JWT token specified in the following header: 

1
X-Access-Token: JWT-String

Delete User Account

Deletes the user that called this route as determined by their access JWT.

DELETE request to /api/v1/protected/user

This route is only implemented to support testing and does not invalidate user access tokens. This is not safe to be called by the frontend client for this reason.

Responses:

200 OK: the user no longer exists

Update User Password

Allows a user to change their password when already authenticated.

POST request to /api/v1/protected/user/change_password with body: 

1
2
3
4
{
  "currentPassword": "secure",
  "newPassword": "secure123"
}
Where passwords should be strings with: - Length 8-20 characters - At least one lowercase - One uppercase - One number - One special character

Response:

200 OK: the password change was successful

400 Bad Request: if the request was malformed

401 Unauthorized: the currentPassword does not match the calling user's current password

Update User Data

Used to update a user's country or privilege level

PUT request to /api/v1/protected/user/:user_id 

1
2
3
4
5
6
7
{
  "country": "UNITED_STATES",
  "privilegeLevel": "ADMIN",
  "firstName": "Test",
  "lastName": "Test",
  "email": "test@gmail.com"
}

Getting User Data

Used to get a user's data

GET request to /api/v1/protected/user/data 

1
2
3
4
5
6
7
8
9
{
    "id": 1,
    "firstName": "Test",
    "lastName": "Test",
    "email": "test@test.com",
    "country": "UNITED_STATES",
    "privilegeLevel": "VOLUNTEER",
    "disabled": "false"
}

Response: 200 OK

Get list of users

Used to return the list of users. Admin only route.

GET request to /api/v1/protected/user/

Response: 200 OK 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "users": [
            {
              "firstName": "firstName",
              "lastName": "lastName",
              "id": 1,
              "email": "email@email.com",
              "country": "dominica",
              "privilegeLevel": "ADMIN",
              "disabled": "false"
            },
            {
              "firstName": "firstName2",
              "lastName": "lastName2",
              "id": 2,
              "email": "email@email2.com",
              "country": "united_states",
              "privilegeLevel": "OFFICER",
              "disabled": "false"
            },
            {
              "firstName": "firstName3",
              "lastName": "lastName3",
              "id": 3,
              "email": "email@email3.com",
              "country": "united_states",
              "privilegeLevel": "VOLUNTEER",
              "disabled": "false"
            }
           ]
}

Also has the option to get a list of users by country GET request to /api/v1/protected/user/?country=<country_name>

(Notice this request was made with the country_name being united_states)

Response: 200 OK 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "users": [
            {
              "firstName": "firstName2",
              "lastName": "lastName2",
              "id": 2,
              "email": "email@email2.com",
              "country": "united_states",
              "privilegeLevel": "OFFICER",
              "disabled": "false"
            },
            {
              "firstName": "firstName3",
              "lastName": "lastName3",
              "id": 3,
              "email": "email@email3.com",
              "country": "united_states",
              "privilegeLevel": "VOLUNTEER",
              "disabled": "false"
            }
           ]
}

Disable a user account (Admin Only)

Used to disable a user's account based on the passed user id

POST request to /api/v1/protected/user/disable/:user_id

Responses:

200 OK : Account successfully disabled

401 Unauthorized: the user is not authenticated

400 User not found: no user with the given id could be found

Re-enable a user account (Admin Only)

Used to re-enable a disabled user's account based on the passed user id

POST request to /api/v1/protected/user/enable/:user_id Responses:

200 OK: Account successfully enabled

401 Unauthorized: the user is not authenticated

400 User not found: no user with the given id could be found

Get list of disabled users

Used to return the list of disabled users. Admin only route.

GET request to /api/v1/protected/user/disabled

Response: 200 OK 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "users": [
            {
              "firstName": "firstName",
              "lastName": "lastName",
              "id": 1,
              "email": "email@email.com",
              "country": "dominica",
              "privilegeLevel": "ADMIN",
              "disabled": "true"
            },
            {
              "firstName": "firstName2",
              "lastName": "lastName2",
              "id": 2,
              "email": "email@email2.com",
              "country": "united_states",
              "privilegeLevel": "OFFICER",
              "disabled": "true"
            },
            {
              "firstName": "firstName3",
              "lastName": "lastName3",
              "id": 3,
              "email": "email@email3.com",
              "country": "united_states",
              "privilegeLevel": "VOLUNTEER",
              "disabled": "true"
            }
           ]
}

Also has the option to get a list of users by country GET request to /api/v1/protected/user/?country=<country_name>

(Notice this request was made with the country_name being united_states)

Response: 200 OK 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "users": [
            {
              "firstName": "firstName2",
              "lastName": "lastName2",
              "id": 2,
              "email": "email@email2.com",
              "country": "united_states",
              "privilegeLevel": "OFFICER",
              "disabled": "true"
            },
            {
              "firstName": "firstName3",
              "lastName": "lastName3",
              "id": 3,
              "email": "email@email3.com",
              "country": "united_states",
              "privilegeLevel": "VOLUNTEER",
              "disabled": "true"
            }
           ]
}

Made with Material for MkDocs