Login and Token Endpoints
Common Headers:
For any request with a body it is assumed that this header exists:
Content-Type: application/json
#### Access Token Composition:
``` json
{
"userId": INT,
"adminLevel": INT
}
- adminLevel: integer describing the user's privilege level.
- 1: General Member
- 2: Admin
Note:
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.
"Given access token is expired or invalid"
Unprotected Routes
These routes are called by a user that is not yet authenticated.
**These routes all have the prefix api/v1/
POST user/login
Used for logging in.
Request
Body:
{
"email" : EMAIL,
"password" : STRING
}
Responses
201 Created
The username/password combination is valid. Includes distinct access and refresh tokens for the given user.
Body:
{
"accessToken" : JWT,
"refreshToken" : JWT
}
400 Bad Request
Malformed request.
401 Unauthorized
The username/password combination is invalid.
POST user/login/refresh
Used for getting a new access token.
Request
Headers:
X-Refresh-Token : JWT
Responses
201 Created
The refresh token is valid and has not yet expired. Response includes a new unique access_token.
Body:
{
"accessToken" : JWT,
}
401 Unauthorized
The refresh token is invalid.
DELETE user/login
Used for logging out.
Request
Headers:
X-Access-Token : JWT
X-Refresh-Token : JWT
Responses
204 No Content
Logout successful.
POST user/signup
Used for signing up a new user.
Request
Body
{
"username": STRING,
"email" : EMAIL,
"password" : STRING,
"firstName" : STRING,
"lastName" : STRING
}
- EMAIL: Is a valid email string.
- PASSWORD: Is a valid password string that is at least 8 characters.
Responses
201 Created
The username and email are still available, and an account has been successfully created.
Body:
{
"accessToken" : JWT,
"refreshToken" : JWT
}
400 Bad Request
Malformed request body.
409 Conflict
The given email or username is already in use.
"Error creating new user, given email %s already used"
"Error creating new user, given username %s already used"
POST user/forgot_password/request
Used to send a reset password email to a user if they have forgotten their password
Request
{
"email": STRING
}
Responses
200 OK
The email was sent to the user successfully
400 BAD REQUEST
The given email is not associated with any user account
POST user/forgot_password/reset
Used to reset a user's password after they have requested a forget password link
Request
{
"secret_key": STRING,
"new_password": STRING
}
The secret key should be determined by the frontend link that the user clicked from their email.
passwords should be strings with length >= 8 characters.
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.
GET user/verify/:secret_key
Used for confirming an account's email
Request
Path Params
- 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.
TODO: GET user/create_secret/:user_id
Used for creating secret keys for users.
Request
PATH: GET user/create_secret/:user_id
Responses
200 OK
A secret key was created and stored for the given user.
400 BAD REQUEST
The given user id could not be found.
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.
X-Access-Token: JWT-String
**These routes all have the prefix api/v1/protected/
DELETE /user
Deletes the user that called this route as determined by their access JWT.
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
POST /user/change_password
Allows a user to change their password when already authenticated.
Request
{
"currentPassword": STRING,
"newPassword": STRING
}
passwords should be strings with length >= 8 characters.
Responses
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.
POST /user/change_username
Allows a user to change their username when already authenticated.
Request
{
"newUsername": STRING,
"password": STRING
}
New username must be unique (not already in use by another user).
Responses
200 OK
The username change was successful.
400 BAD REQUEST
If the request was malformed.
401 Unauthorized
The password does not match the calling user's current password.
409 Conflict
The given
newUsernameis already in use.