HOST: http://www.google.com/ --- Userific-Server --- --- Welcome to the documentation for the Userific Server project. Userific provides an way to manage users in your application via a rest api. Userific supports several different backends. No matter which backend is used, the RESTful api is the same for the server --- -- User Resources The following is a section of resources related to user management. The userific server supports the following api RESTful endpoints * [/register](#post-%2Fregister) * [/confirmEmail](#post-%2FconfirmEmail) * [/authenticate](#post-%2Fauthenticate) * [/generatePasswordResetToken](#post-%2FgeneratePasswordResetToken) * [/changeEmail](#post-%2FchangeEmail) * [/changePassword](#post-%2FchangePassword) * [/resetPassword](#post-%2FresetPassword) * [/grantRoleForEmail](#post-%2FgrantRoleForEmail) * [/ping](#get-%2Fping) -- Register a new user account When registering a user account, the following fields are required * `email` - the email address used to login to the account * `password` - the password used to login to the account' ## Valid Registration If the `register` request completes correctly, a status code of `201` will be returned. The response will include the following fields * `"_id": "the id of the user record in the backend datastore"` * `"email": "the email address stored in the backend datastore. This should be the same as the input email"` ## Invalid If either the email or password is missing or invalid, a status code of `409` will be returned. The response will include the following fields * `"code": "MissingParameter"` * `"message": "register failed"` * `"reason": "missing_parameters"` * `"errors": [ { "param": "password", "msg": "password must be at least 4 characters long", "value": "foo" }, { "param": "email", "msg": "required", "value": "foo.com" }]` ## Email Taken If the supplied email is already registered to another account, a statusCode of `409` will be returned. The response will include the following fields * `"code": "InvalidArgument"` * `"message": "register failed"` * `"reason": "email_taken"` ## Internal Errors If there is an error in the server or an error querying the database, a status cod of `500` will be returned. The response will include the following fields * `"code": "InternalError"` * `"messge": "register failed"` POST /register > Content-Type: application/json { "email":"foo@example.com", "password": "barPassword" } < 201 < Content-Type: application/json { "_id": "fooUserID", "email": "foo@example.com", "confirmToken": "41a55f3f085b07271a33bf3dd30e079a" } +++++ < 409 < Content-Type: application/json; charset=utf-8 {"code": "InvalidArgugment", "message": "register failed", "reason": "email_taken" } +++++ < 409 < Content-Type: application/json; charset=utf-8 {"code": "MissingParameter", "message": "Register failed", "errors": [ { "param": "email", "msg": "required" }, { "param": "password", "msg": "password must be at least 4 characters long" }]} Confirm email for new Register After a user registers for an account, they need to be able to confirm their email. A confirmToken gets generated on each registration and sent to the user somehow, most likely via email. The email contains a link to this `confirmEmail` route with a GET parameter containing the confirmToken * `confirmToken` - confirmation token emailed to the user ## Valid Confirmation If the `confirmEmail` request completes correctly, a status code of `200` will be returned. The response will include the following fields * `"_id": "the id of the user record in the backend datastore"` * `"email": "the email address stored in the backend datastore. This should be the same as the input email"` ## Missing token If either the `confirmToken` is missing, a statusCode of `409` will be returned allow with the response * `"code": "MissingParameter"` * `"messge": "register failed"` * `"reason": "missing_parameters"` * "errors": [{ "param": "confirmToken", "msg": "required", "value": "" }]` ## Invalid Token If the supplied `confirmToken` is not found in the database, a statusCode of `403` will be returned along with the response * `"code": "NotAuthorized"` * `"messge": "confirmEmail failed"` * `"reason": "invalid_token"` ## Internal Errors If there is an error in the server or an error querying the database, a status cod of `500` will be returned. The response will include the following fields * `"code": "InternalError"` * `"messge": "confirmEmail failed"` POST /confirmEmail > Content-Type: application/json { "confirmToken": "asdf34vfdsfsdaoj29dkscnasd02ondwfoij" } < 200 < Content-Type: application/json { "_id": "fooUserID", "email": "foo@example.com" } +++++ < 409 < Content-Type: application/json; charset=utf-8 {"code": "MissingParameter", "message": "Register failed", "reason": "missing_parameter", "errors": [ { "confirmToken": "email", "msg": "required" }]} +++++ < 403 < Content-Type: application/json; charset=utf-8 {"code": "NotAuthorized", "message": "Confirm Email failed", "reason": "invalid_token" } Authenticate an existing user account When authenticating a user account, the following fields are required * `email` - the email address used to login to the account * `password` - the password used to login to the account' ## Valid Authorization If the `authenticate` request completes correctly, a status code of `200` will be returned. The response body will include the following fields * `email: foo@example.com` * `_id: userIDInDatabaseHere` ## Invalid Username or Password If the username or password is incorrect, a status code of `401` will be returned along with the response body * `"message": "authenticate failed"` * `"code": InvalidCredentials` * `"reason": "invalid_credentials"` ## Unconfirmed If the username and password are correct but the user has not yet confirmed the email, a status code of `403` will be returned along with the body * `"message": "authenticate failed"` * `"reason": "unconfirmed"` * `"code": "NotAuthorized"` ## Missing Parameters If either the username or password is missing, a status code of `409` will be returned. * `"message": "authenticate failed"` * `"reason": "missing_paramters"` * `"code": "MissingParameter"` * `"errors": ["param": "email", "msg": "required", "param": "password", "msg": "required"]` Finally if there is an error in the server or an error querying the database, a status cod of `500` will be returned. The response body will include the fields * `"message": "authenticate failed"`, * `"code": "InternalError"` POST /authenticate > Content-Type: application/json { "email":"foo@example.com", "password": "barPassword" } < 200 < Content-Type: application/json { "_id": "fooUserID", "email": "foo@example.com" } +++++ < 401 < Content-Type: application/json; charset=utf-8 {"code":"InvalidCredentials","message":"user not found"} +++++ < 403 < Content-Type: application/json; charset=utf-8 {"code":"NotAuthorized","message":"authenticate failed", "reason": "unconfirmed" } +++++ < 409 < Content-Type: application/json; charset=utf-8 {"code": "MissingParameter", "message": "authenticate failed", "reason": "missing_parameters", "errors": [ { "param": "email", "msg": "required" }]} +++++ < 409 < Content-Type: application/json; charset=utf-8 {"code": "MissingParameter", "message": "authenticate failed", "reason": "missing_parameters", "errors": [ { "param": "password", "msg": "required" }]} Change email for an existing user account When changing email, the following fields are required * `currentEmail` - the email address of the account * `password` - the password used to login to the account * `newEmail` - the new email address of the account ## Success If the `changeEmail` request completes correctly, a status code of `200` will be returned. You can the call the authenticate route using the new email address and password to login ## Missing Parameter If one or more of the posted parameters is either missing or incorrect, a status code of `409` will be returned. The response will include the following fields * `"code": "MissingParameter"` * `"message": "changeEmail failed"` * `"errors": [ { "param": "currentEmail", "msg": "required" }, { "param": "newEmail", "msg": "required" }, { "param": "password", "msg": "required" } ]` ## Invalid Password If the supplied password is not correct for the supplied `currentEmail` parameter, a status code of `401` will be returned. The response will include the following fields ```javascript { "code":"InvalidCredentials", "message":"user not found" } ``` POST /changeEmail > Content-Type: application/json {"currentEmail":"foo@example.com", "password": "fooPassword", "newEmail": "newEmail2@example.com" } < 200 < Content-Type: application/json; charset=utf-8 { "_id": "fooUserID", "email": "newEmail2@example.com" } +++++ < 401 < Content-Type: application/json; charset=utf-8 {"code":"InvalidCredentials","message":"user not found"} +++++ < 409 < Content-Type: application/json; charset=utf-8 {"code": "MissingParameter", "message": "changeEmail failed", "errors": [ { "param": "currentEmail", "msg": "required" }, { "param": "newEmail", "msg": "required" }, { "param": "password", "msg": "required" }]} Change password for an existing user account When changing password, the following fields are required * `currentPassword` - the password address of the account * `email` - the email address used to login to the account * `newpassword` - the new password of the account ## Success If the `changePassword` request completes correctly, a status code of `200` will be returned. You can then call the authenticate route using the email address and new password to login. On succesful change password requests, the response will include the following fields ```javascript { "_id": "fooUserID", "email": "foo@example.com" } ``` ## Invalid Password If the supplied `currentPassword` is not correct for the supplied `email` parameter, a status code of `401` will be returned. The response will include the following fields ```javascript { "code":"InvalidCredentials", "message":"user not found" } ``` ## Missing Parameters If any of the required fields are either missing or invalid, a status code of `409` will be returned. The response will include the following fields ```javascript { "code": "MissingParameter", "message": "changePassword failed", "errors": [ { "param": "currentPassword", "msg": "required" }, { "param": "newPassword", "msg": "required" }, { "param": "email", "msg": "required" } ] } ``` POST /changePassword > Content-Type: application/json { "email":"foo@example.com", "currentPassword": "fooPassword", "newPassword": "newBarPassword2" } < 200 < Content-Type: application/json { "_id": "fooUserID", "email": "foo@example.com" } +++++ < 401 < Content-Type: application/json; charset=utf-8 {"code":"InvalidCredentials","message":"user not found"} +++++ < 409 < Content-Type: application/json; charset=utf-8 {"code": "MissingParameter", "message": "changePassword failed", "errors": [ { "param": "currentPassword", "msg": "required" }, { "param": "newPassword", "msg": "required" }, { "param": "email", "msg": "required" }]} Generate a password reset token for a given account. When a user forgets their login password and needs to reset the password to a new one, the system must first confirm the user another way. One possibility is via their email address. the `/generatePasswordResetToken` api endpoint allows a user to begin the reset process. The backend will generate a reset token and associate it with the user in the database. Since the userific server is intended to be used as a public api, the reset token is not returned back in the response body. To email the reset token to the user, your web server must query the database itself a fetch the reset token. When generating a password reset token, the following fields are required * `email` - the email address used to login to the account ## Success If the `generatePasswordResetToken` request completes correctly, a status code of `200` will be returned. You can then fetch the reset token from the data-store and email it to the user. The response will include the following fields ```javascript { "_id": "fooUserID", "email": "foo@example.com" } ``` ## Missing Parameters If any of the required fields are either missing or invalid, a status code of `409` will be returned. The response will include the following fields ```javascript { "code": "MissingParameter", "message": "generatePasswordResetToken failed", "reason": "missing_parameter", "errors": [ { "param": "email", "msg": "required" } ] } ``` ## Unconfirmed User If the endpoint is called with an email address for a user who has registered but not yet confirmed their email, a status code of `403` will be returned. The response body will include the following fields: ```javascript { "code": "NotAuthorized", "message": "generatePasswordResetTokenFailed", "reason": "unconfirmed" } ``` POST /generatePasswordResetToken > Content-Type: application/json { "email":"foo@example.com" } < 200 < Content-Type: application/json { "_id": "fooUserID", "email": "foo@example.com" } +++++ < 403 < Content-Type: application/json; charset=utf-8 {"code":"Not Authorized","message":"generatePasswordResetTokenFailed", "reason": "unconfirmed" } +++++ < 409 < Content-Type: application/json; charset=utf-8 {"code": "MissingParameter", "message": "generatePasswordResetTokenFailed", "errors": [ { "param": "email", "msg": "required" } ] } Ping the server to make sure it online GET /ping < 200 < Content-Type: application/json { "message": "pong"} When resetting a passsword, the following fields are required * `resetToken` - the token emailed to the user from the generatePasswordResetToken request ## Success If the `resetPassword` request completes correctly, a status code of `200` will be returned. A new random password will be returned back in the response which will include the following fields ```javascript { "password": "new password here' } ``` ## Missing Parameters If any of the required fields are either missing or invalid, a status code of `409` will be returned. The response will include the following fields ```javascript { "code": "MissingParameter", "message": "resetPassword failed", "reason": "missing_parameter", "errors": [ { "param": "resetToken", "msg": "required" } ] } ``` ## Unconfirmed User If the endpoint is called with an email address for a user who has registered but not yet confirmed their email, a status code of `403` will be returned. The response body will include the following fields: ```javascript { "code": "NotAuthorized", "message": "resetToken", "reason": "unconfirmed" } ``` ## Invalid Token If the endpoint is called with a `resetToken` that does not exist in the database, a status code of `401` will be returned. The response body will include the following fields: ```javascript { "code": "InvalidCredentials", "message": "resetToken", "reason": "invalid_reset_token" } ``` POST /resetPassword > Content-Type: application/json { "resetToken":"foo token here" } < 200 < Content-Type: application/json { "password": "new password here" } +++++ < 403 < Content-Type: application/json; charset=utf-8 {"code":"NotAuthorized","message":"resetPassword failed", "reason": "unconfirmed" } +++++ < 409 < Content-Type: application/json; charset=utf-8 {"code": "MissingParameter", "message": "resetToken", "reason": "missing_parameter", errors": [ { "param": "email", "msg": "required" } ] } +++++ < 401 < Content-Type: application/json; charset=utf-8 {"code":"InvalidCredentials","message":"resetPassword failed", "reason": "invalid_reset_token" } Ping the server to make sure it online GET /ping < 200 < Content-Type: application/json { "message": "pong"} Grant role for an existing user When granting a role for a user, the following fields are required * `adminEmail` - the email address of an existing adminstrator account * `adminPassword` - the password for an existing administrator account * `email` - the email address of the user to whom the system will grant the role * `role` - the role to grant, which should be one of `['user', 'staff', 'admin']` ## Success If the `grantRoleForEmail` request completes correctly, a status code of `201` will be returned. The response will look as follows ```javascript { role: 'staff', email: 'foo@example.com', message: 'role granted successfully' } ``` ## Invalid Admin credentials If the supplied admin user email or password are incorrect, a status code of `401` will be returned. The response will include the following fields ```javascript { "code":"InvalidCredentials", "message":"user not found", "reason": "not_authorized" } ``` ## Invalid Role If the supplied `role` is not a valid role name, a status code of `409` will be returned. The response will look as follows { code: 'InvalidArgument', message: 'failed to get role', error: 'invalid role name', reason: 'role_not_found' } ## Missing Parameters If any of the required fields are either missing or invalid, a status code of `409` will be returned. The response will include the following fields ```javascript { "code": "MissingParameter", "message": "changePassword failed", "errors": [ { "param": "adminEmail", "msg": "required" }, { "param": "adminPassword", "msg": "required" }, { "param": "email", "msg": "required" } { "param": "role", "msg": "required" } ] } ``` POST /grantRoleForEmail > Content-Type: application/json { "adminEmail": "admin@example.com", "adminPassword": "barPassword" email":"foo@example.com", "role": "staff" } < 201 < Content-Type: application/json { "role": "staff", "email": "foo@example.com", "message": "role granted successfully" } +++++ < 401 < Content-Type: application/json; charset=utf-8 {"code":"InvalidCredentials","message":"user not found", "reason": "not_authorized"} +++++ < 409 < Content-Type: application/json; charset=utf-8 {"code": "MissingParameter", "message": "changePassword failed", "errors": [ { "param": "adminEmail", "msg": "required" }, { "param": "adminPassword", "msg": "required" }, { "param": "email", "msg": "required" }, { "param": "role", "msg": "required" }]}