In the first part of this blog series, you were able to learn about authentication infrastructure, token management and other parts of the Baasic membership system. This time, we’ll cover its additional core aspects. Let’s see how to use and build upon Baasic user registration, account activation and password recovery features.

User Registration

It’s safe to say that these days every application needs to have basic user registration functionality in place. While it can be optional, it simply has to exist somewhere. Taking this into account, Baasic itself - being a rich BaaS (and may I say much more than that) - has the user registration functionality implemented and ready to be used. In order to register the user with the custom Baasic application, you only need to make one call to the the register endpoint. In the other words, you need to invoke the POST method of the user register endpoint:

curl -X POST -H "Content-Type: application/json" 
-d "{
        "activationUrl": "<your-activation-url>",
        "creationDate":"2015-07-19T19:53:02.528Z",
        "challengeIdentifier": "<reCaptcha-challenge-identifier>",
        "challengeResponse": "<reCaptcha-challenge-response>",
        "email":"test@gmail.com",
        "userName":"test",
        "password":"test123!",
        "confirmPassword":"test123!",
        "isApproved": false
    }"
https://api.baasic.com/<version>/<api-key>/register

If this action completes successfully, you will get 200 OK HTTP response code and JSON response similar to the one below:

{
    "creationDate":"2015-07-19T19:53:50.067784Z",
    "dashboardSettings":{},
    "email":"test@gmail.com",
    "isApproved":false,
    "isLockedOut":false,
    "name":"test8",
    "roles":[],
    "userName":"test",
    "id":"lLceNBgms46542D5LqK4f3",
    "_links":{
        "post":{
            "href":"http://api.baasic.com/beta/membership-blog/register",
            "templated":false
        },
        "activate":{
            "href":"http://api.baasic.com/beta/membership-blog/register/activate/{{activationToken}}",
            "templated":true
        }
    },
    _embedded":{}
}

If you take a look at the response, you can see it contains data closely tied to the user resource, in addition to the user data that was initially sent in the request. Please refer to the documentation page to get a complete view of the response object’s properties and response codes.

Account Activation

Upon each successful registration - if account activation is mandatory (i.e. isApproved property set to false) - the user has to activate his account to be able to access the Baasic application. In order to activate the account, you have to preserve the activation token which is automatically sent as a response from the registration endpoint. As a matter of fact, it will be embedded into activationUrl, which usually leads to the account activation page. To get a broader view please visit the previous blog post, and search for the Account Activation section.

In order to activate the user, you need to make a PUT request which will update user’s account:

curl -X PUT -H "Content-Type application/x-www-form-urlencoded" -d "" https://api.baasic.com/<version>/<api-key>/register/activate/<activation-token>

The response will return true if activation is successful, otherwise it can return various response codes.

Password Recovery

From time to time users simply forget their passwords, and no one can blame them as there are a lot of different passwords used in different applications. This is where password recovery mechanism kicks in. Since the user’s password is a sensitive piece of data, password recovery is a two-step process. First step generates the password recovery token and sends a notification email to the user’s email account. The subsequent step is used to actually change the existing password.

In practice, the password recovery mechanism has one endpoint with two different HTTP methods, POST and PUT.

To initiate the password recovery process, user needs to type its username, enter the reCaptcha code, and send the information to the endpoint as shown below:

curl -X POST -H "Content-Type application/json"
-d "{
        "challengeIdentifier": "<reCaptcha-challenge-identifier>",
        "challengeResponse": "<reCaptcha-challenge-response>",
        "recoverUrl": "<application-password-recovery-url>",
        "username": "<username>"
    }
https://api.baasic.com/<version>/<api-key>/recover-password

If everything goes well, you will get a 201 Created HTTP response code, and subsequently Baasic will send a password recovery email message. It will include the link to the password recovery url, which basically leads to the recoverUrl with an embedded password recovery token. Password recovery token is a token which has to be used in order to change the user’s password.

curl -X PUT -H "Content-Type: application/json"
-d "{
        "passwordRecoveryToken": "<password-recovery-token>",
        "newPassword": "<new-password>"
    }"
https://api.baasic.com/<version>/<api-key>/recover-password

If PUT method responds with the success code (HTTP 200 OK), user’s password will be changed, and from now on your user will be able to login into the application with his new credentials.

Having the password recovery mechanism briefly described, we have covered all the basic membership features. In the next post we’ll cover more complex features, including user management, permissions and roles, and other staff that makes the foundation of all great applications. Please stay tuned and send us your questions, comments and suggestions for new features.

Feel free to leave a comment

comments powered by Disqus