User Registration Service

What happens when users register for an application?

Photo by Micah Williams on Unsplash

These days we have so many applications which require us to register to access their application. If the registration is successful then we are allowed to login the application. Let us learn what happens in the background when we signup for any application.

User Registration

A registration request must provide a user object as a collection of key/value properties. The collection must contain a property marked as identity as well as the password property. Additionally, the email property is required if your application is configured to confirm email addresses for the registered users.

Method : POST

Endpoint URL :

http://localhost:8080/api/users/register

Request Headers : Content-Type:application/json

where Content-Type must be set to application/json. This header is mandatory.

Request Body :

{  
  "first_name" : value,  
  "last_name" : value,  
  "email" : value,
  "password" : value 
}

Response Body :

{
  "objectId" : value,
  "first_name" : value,  
  "last_name" : value,  
  "email" : value,
  "password" : value 
}

Error Codes :

When the server-side reports an error, it returns a JSON object in the following format :

{  
  "message" : error-message,  
  "code" : error-code  
}

Create Email Confirmation URL

A confirmation email message includes a special link the user clicks to confirm their email address. When the link is clicked and the link is not expired, the user status changes from EMAIL_CONFIRMATION_PENDING to ENABLED. The email message delivered to the user can be created using Amazon Simple Email Service. There are scenarios when the link needs to be generated in your application logic, for instance, if you need to send it out via text message or if you need to generate the confirmation email dynamically. The API below is for obtaining a confirmation URL for a user.

Method : POST

Endpoint URL :

http://localhost:8080/api/users/resendconfirmation/<identity>

where <identity> value in a column marked as identity in the Users table. By default application has email as the identity column. In that case the parameter for the API should be the email address of a user.

Request Headers : Content-Type:application/json

where Content-Type must be set to application/json. This header is mandatory.

Request Body : None

Response Body : A JSON document with the following structure.

{  
  "confirmationURL": "https://xxxx.backendless.app/api/............"  
}

Error Codes :

When the server-side reports an error, it returns a JSON object in the following format :

{  
  "message" : error-message,  
  "code" : error-code  
}

Email Verification

This API resends the email confirmation email message to a user. It applies only to the apps which have the “Require email confirmation” option enabled. If the user status is “email confirmation pending”, then an email with the confirmation link is resent, otherwise an error occurs.

Method : POST

Endpoint URL :

http://localhost:8080/api/users/resendconfirmation/<identity>

where <identity> value in a column marked as identity in the Users table. By default application has email as the identity column. In that case the parameter for the API should be the email address of a user.

Request Headers : Content-Type:application/json

where Content-Type must be set to application/json. This header is mandatory.

Request Body : None

Response Body : None. If the API request completes successfully, it means an email confirmation message has been sent to the user. Otherwise, an error will be returned.

Error Codes :

When the server-side reports an error, it returns a JSON object in the following format :

{  
  "message" : error-message,  
  "code" : error-code  
}

User Login

The login operation requires two properties : one marked as user identity and the second is password. It automatically assigns the "AuthenticatedUser" role to all successfully logged in users. The role can be used to differentiate access to various resources (data in the database, files, messaging channels) between authenticated users and guests.

Method : POST

Endpoint URL :

http://localhost:8080/api/users/login

Request Headers : Content-Type:application/json

where Content-Type must be set to application/json. This header is mandatory.

Request Body :

{  
  "login" : value,
  "password" : value 
}

The "login" key must contain the value for a property marked as identity. Identity is uses for login and restore password operations. As users register, server will ensure the value for the identity property is unique.

Response Body :

{  
  "objectId" : value,  
  "user-token": value,   
  "prop-name1":value,  
  "prop-name2":value,  
  "prop-name3":value,  
  ...  
}

The objectId property is a unique identifier assigned by the server to the user account. The user-token value identifies the user session initiated by the login operation. Both of these values objectId and user-token are required for updating a user in the database.

Error Codes :

When the server-side reports an error, it returns a JSON object in the following format :

{  
  "message" : error-message,  
  "code" : error-code  
}

Maintaining User Session

The user-token value returned in the sign-in API must be used in the subsequent requests in order to maintain the user session. The value uniquely identifies both the user and the session on the server and is used to enforce security policy, apply user and roles permissions and track usage analytics. For all requests made after the login, the user-token value must be sent in the HTTP header :

"user-token" : value

Validating User Login

The user-token value can be saved in the client application so it can be used when the application is restarted. This helps in streamlining the user experience since the user of the application does not need to login again. However, when the application restarts, it needs to check if the underlying user token, and hence the user session are still valid. This can be accomplished with the API below :

Method : GET

Endpoint URL :

http://localhost:8080/api/users/isvalidusertoken/<userToken>

where <userToken> is used for validation. The value of the user token is returned as a result of the login API request.

Return value :

The server returns a boolean value of true if token is valid, false otherwise.

Logout

The Logout operation terminates user session and disassociates the AuthenticatedUser role from the subsequent requests made by the client application.

Method : GET

Endpoint URL :

http://localhost:8080/api/users/logout

Request Headers :

user-token: value-of-the-user-token-header-from-login

where user-token a value returned in the response for the preceding Login operation. The value identifies the user to be logged out. This header is mandatory.

Error Codes :

When the server-side reports an error, it returns a JSON object in the following format :

{  
  "message" : error-message,  
  "code" : error-code  
}

In this article we covered the details about the user registration. Many applications are also using OAuth. OAuth is used to grant websites or applications access to their information on other websites but without giving them the passwords. We will cover and discuss OAuth workflow in future articles. Stay Tuned. Happy Learning! 🎃