Table of Contents

    API

    Mock Server

    Use this URL to access a mockup of the API server. Your traffic will be recorded and compared to the documentation. You'll find your traffic analysis in the inspector or directly here in the documentation, right next to each resource.

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

POST

/register

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"

Response

201 (Created)
Content-Type: application/json
{ "_id": "fooUserID", "email": "foo@example.com", "confirmToken": "41a55f3f085b07271a33bf3dd30e079a" }

Response

409 (Conflict)
Content-Type: application/json; charset=utf-8
{"code": "InvalidArgugment", "message": "register failed", "reason": "email_taken" }

Response

409 (Conflict)
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" }]}

POST

/confirmEmail

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"

Response

200 (OK)
Content-Type: application/json
{ "_id": "fooUserID", "email": "foo@example.com" }

Response

409 (Conflict)
Content-Type: application/json; charset=utf-8
{"code": "MissingParameter", "message": "Register failed", "reason": "missing_parameter", "errors": [ { "confirmToken": "email", "msg": "required" }]}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{"code": "NotAuthorized", "message": "Confirm Email failed", "reason": "invalid_token" }

POST

/authenticate

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"

Response

200 (OK)
Content-Type: application/json
{ "_id": "fooUserID", "email": "foo@example.com" }

Response

401 (Unauthorized)
Content-Type: application/json; charset=utf-8
{"code":"InvalidCredentials","message":"user not found"}

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{"code":"NotAuthorized","message":"authenticate failed", "reason": "unconfirmed" }

Response

409 (Conflict)
Content-Type: application/json; charset=utf-8
{"code": "MissingParameter", "message": "authenticate failed", "reason": "missing_parameters", "errors": [ { "param": "email", "msg": "required" }]}

Response

409 (Conflict)
Content-Type: application/json; charset=utf-8
{"code": "MissingParameter", "message": "authenticate failed", "reason": "missing_parameters", "errors": [ { "param": "password", "msg": "required" }]}

POST

/changeEmail

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

{
  "code":"InvalidCredentials",
  "message":"user not found"
}

Response

200 (OK)
Content-Type: application/json; charset=utf-8
{ "_id": "fooUserID", "email": "newEmail2@example.com" }

Response

401 (Unauthorized)
Content-Type: application/json; charset=utf-8
{"code":"InvalidCredentials","message":"user not found"}

Response

409 (Conflict)
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" }]}

POST

/changePassword

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

{
  "_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

{
  "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

{
 "code": "MissingParameter",
 "message": "changePassword failed",
 "errors": [
   { "param": "currentPassword", "msg": "required" },
   { "param": "newPassword", "msg": "required" },
   { "param": "email", "msg": "required" }
 ]
}

Response

200 (OK)
Content-Type: application/json
{ "_id": "fooUserID", "email": "foo@example.com" }

Response

401 (Unauthorized)
Content-Type: application/json; charset=utf-8
{"code":"InvalidCredentials","message":"user not found"}

Response

409 (Conflict)
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" }]}

POST

/generatePasswordResetToken

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

{
  "_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

{
 "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:

{
 "code": "NotAuthorized",
 "message": "generatePasswordResetTokenFailed",
 "reason": "unconfirmed"
}

Response

200 (OK)
Content-Type: application/json
{ "_id": "fooUserID", "email": "foo@example.com" }

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{"code":"Not Authorized","message":"generatePasswordResetTokenFailed", "reason": "unconfirmed" }

Response

409 (Conflict)
Content-Type: application/json; charset=utf-8
{"code": "MissingParameter", "message": "generatePasswordResetTokenFailed", "errors": [ { "param": "email", "msg": "required" } ] }

GET

/ping

Ping the server to make sure it online

Response

200 (OK)
Content-Type: application/json
{ "message": "pong"}

POST

/resetPassword

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

{
  "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

{
 "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:

{
 "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:

{
 "code": "InvalidCredentials",
 "message": "resetToken",
 "reason": "invalid_reset_token"
}

Response

200 (OK)
Content-Type: application/json
{ "password": "new password here" }

Response

403 (Forbidden)
Content-Type: application/json; charset=utf-8
{"code":"NotAuthorized","message":"resetPassword failed", "reason": "unconfirmed" }

Response

409 (Conflict)
Content-Type: application/json; charset=utf-8
{"code": "MissingParameter", "message": "resetToken", "reason": "missing_parameter", errors": [ { "param": "email", "msg": "required" } ] }

Response

401 (Unauthorized)
Content-Type: application/json; charset=utf-8
{"code":"InvalidCredentials","message":"resetPassword failed", "reason": "invalid_reset_token" }

GET

/ping

Ping the server to make sure it online

Response

200 (OK)
Content-Type: application/json
{ "message": "pong"}

POST

/grantRoleForEmail

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

{
  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

{
  "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

{
 "code": "MissingParameter",
 "message": "changePassword failed",
 "errors": [
   { "param": "adminEmail", "msg": "required" },
   { "param": "adminPassword", "msg": "required" },
   { "param": "email", "msg": "required" }
   { "param": "role", "msg": "required" }
 ]
}

Response

201 (Created)
Content-Type: application/json
{ "role": "staff", "email": "foo@example.com", "message": "role granted successfully" }

Response

401 (Unauthorized)
Content-Type: application/json; charset=utf-8
{"code":"InvalidCredentials","message":"user not found", "reason": "not_authorized"}

Response

409 (Conflict)
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" }]}