user-auth-docs.md

user-auth-api

Public facing user authentication http api.

Instances

Instances that can be returned from the server.

User

{
    "id": "string",
    "login": "string",
    "firstName": "string",
    "lastName": "string",
    "status": "number"
}

Error

{
    "code": "number",
    "error": "string"
}

HTTP error codes

The following HTTP status codes can be returned in the response.

Code	Code string	Error
200	OK	Everything is OK.
204	NoContent	Everything is OK, but there is no content to return.
400	BadRequest	Most probably, the server failed to parse request JSON string or one of the fields is malformed.
401	Unauthorized	The user is not authorized. If this code is returned in any of the requests- meaning the user is not authorized or session expired, the user should be redirected to authentication page.
404	NotFound	The requested path is not found on the server.
405	MethodNotAllowed	The requested path is found but the method is not allowed (wrong), for example, you're using GET where POST should be used.
408	StatusRequestTimeout	The request has timed out.
500	InternalServerError	Something went wrong on the server.

Endpoints

POST /check

Checks if user is authorized and returns a User instance with code 200 or an Error instance and code 401 otherwise.

POST /login

Authorized the user within the service and creates an authorization session. Returns a User instance with code 200 or an Error instance and code 401 otherwise..

Param	Type	Description
login	string	User login.
password	string	User password.

Example request:

{
    "login": "[email protected]",
    "password": "somePassword"
}

POST /logout

Terminates user session within the service. Returns 204.

POST /register

Registers a new user within the service and creates an authorization session. Returns a User instance with code 200 or an Error instance and code 401 otherwise.

Example request:

{
    "login": "[email protected]",
    "password": "somePassword",
    "firstName": "Che",
    "lastName": "Guevara"
}

POST /start-reset

Starts a reset password process. Sends an email to the user that contains the link to reset password. The link leads to https://auth.bar.dev.s9s.io/reset-password?uid=USER_ID&t=RESET_TOKEN. The uid (user id) and the t (token) need to be parsed out from the url and sent to /reset endpoint along with new password. Returns 204 No Content or an Error instance and code 500 otherwise.

Example request:

{
    "login": "[email protected]"
}

POST /reset

Resets the user password if the id and the token are matching. Returns 204 No Content or an Error instance and code 500 otherwise.

Example request:

{
    "id": "5ce560da993911b1162fca9b",
    "token": "4ddb9c2e-e6c8-4cab-a46d-d3dd1a7a6a2b",
    "password": "newPa$$word!"
}

POST /confirm-email

Sets user email as "confirmed" if the id and the token are matching. Returns 204 No Content or an Error instance and code 500 otherwise.

Example request:

{
    "id": "5ce560da993911b1162fca9b",
    "token": "4ddb9c2e-e6c8-4cab-a46d-d3dd1a7a6a2b"
}