Registration, authentication and management of users¶

How to work with coolsignup¶

coolsignup has a REST-like api. You communicate with the coolsignup server by sending http requests to it. The data you post to coolsignup is in json format and the responses you receive are also in this format. The api extensively uses POST requests even for actions without side effects. This departs from the traditional REST canons but helps avoiding problems with potential caching or logging of sensitive data.

In this documentation, we use curl to give examples of how to make requests to the API. curl is a UNIX utility used to send http requests. Obviously, when using coolsignup in your application, you will use whatever is the preferred way to send http requests in the particular language or framework you’re working with.

The requests you make are to be made server side: the web application running on your servers makes the requests to the coolsignup server. The end user must not be able to access the coolsignup server directly.

Registering users with an email address and a password¶

1. Check the email address¶

The first step is to ask the user for their email address and to check the email address. Say your user entered the user@example.com email address in a HTML form. Make the following request to coolsignup:

curl -X POST /api/email/send-registration-code
     -d '{"email": "user@example.com"}'

This will send an email containing an email confirmation link to the user. If the emailCodeLink parameter of your configuration file is "https://auth.mysite.org/code/", then this link will look like https://auth.mysite.org/code/QmQQaP0IKiDrGtdtjbVa5V8jjNYDsI8K.

As stated in the Internationalization section, you can add a lang query string parameter to your url. For example:

curl -X POST /api/email/send-registration-code?lang=fr
     -d '{"email": "user@example.com"}'

Then the user will receive an email in French.

If all is well, you get the following response:

{"success": true}

If something goes wrong, you receive:

{"success": false, "error": "message explaining what went wrong"}

For example:

{
    "success": false,
    "error": "This email already belongs to a registered account"
}

2. Check the confirmation email link¶

Assuming all went well in the previous step, your user has received a link looking like this:

https://auth.mysite.org/code/QmQQaP0IKiDrGtdtjbVa5V8jjNYDsI8K

They clicked on it or maybe they copy pasted it in the url bar of their browser.

You extract the code from the url, which, in this example, is QmQQaP0IKiDrGtdtjbVa5V8jjNYDsI8K.

You need to check if the code is valid. The goal of this step is only to make sure your user didn’t screw up when clicking or copy-pasting the link.

curl -X POST /api/email/check-registration-code
     -d '{"code": "QmQQaP0IKiDrGtdtjbVa5V8jjNYDsI8K"}'

The response will be either:

{"success": true}

or

{"success": false, "error": "Invalid registration code."}

You can add a lang parameter to the query string to receive the error message in a different language.

If the code is not valid, you should inform your user about that so that they double check the link they followed. If the code is valid, you can proceed to the next step: registering the user.

3. Register the user¶

Use the registration code you extracted from the url in step 2. Then post to the following url:

curl -X POST /api/email/register -d '{
    "registrationCode": "QmQQaP0IKiDrGtdtjbVa5V8jjNYDsI8K",
    "password": "my password is strong as hell"
}'

This will register the user with the password supplied.

The result you get is either:

{"success": true, "_id": "5cfae1ae7be455eeb9580c9c"}

where _id is the user id of the new user.

or, an error response such as:

{"success": false, "error": "Password too easy to guess."}
{"success": false, "error": "Invalid registration code."}

Once you have created an account, you must activate it if you want the user to be able to login. This is the subject of the next section.

Activate the user’s account¶

Even when the user’s email was successfully checked, coolsignup does not automatically activate the account after registration. Maybe you’ll want to manually check registrations before accepting them, or maybe you’ll want to verify users by sending a code by SMS. So, once you’ve made all these verifications, you post the _id of your user to the following url to activate the account:

POST /api/activate-user {"_id": "5cfae1ae7be455eeb9580c9c"}

You’ll get

{"success": true}

or an error such as:

{"success": false, "error": "no such user"}

Login¶

To log your user in, post to the following url:

curl -X POST /api/email/login -d '{
    "email": "user@example.com",
    "password": "my password is strong as hell"
}'

You’ll get either something like:

{
    "success": true,
    "authToken": "bmbfVLnt95S33IY6...MjaPTuZmjdWmpAQ-QA8OStz"
}

or an error:

{"success": "false", "error": "Wrong identifiers"}

The “authToken” value is a string that was cryptographically signed using the private key in your coolsignup.conf. This string can be used to identify your user when using the rest of the coolsignup api. Typically, in a web app, you would store that authToken string in a cookie in the client’s browser. In a phone app, you would store it in the local storage.

On login, you might want to retrieve the _id of your user. This is a string that uniquely identifies your user. You might also want to retrieve some fields about your user, for example a screen name, or a favorite color.

To retrieve user fields on login, add a "fields" list of fields to your request. For example:

curl -X POST /api/email/login -d '{
    "email": "user@example.com",
    "password": "my password is strong as hell",
    "fields": ["_id", "screenName", "favoriteColor"]
}'

You get

{
    "success": true,
    "authToken": "bmbfVLnt95S33IY6...MjaPTuZmjdWmpAQ-QA8OStz",
    "user" : {
        "_id": "5cfae1ae7be455eeb9580c9c",
        "screenName": "Mauricio",
        "favoriteColor": "orange"
    }
}

Log out¶

To logout, post to the following url.

curl -X POST /api/logout
     -d '{"authToken": "bmbfVLnt95S33IY6...MjaPTuZmjdWmpAQ-QA8OStz"}'

This action succeeds even if the authToken is invalid or was deleted from a previous logout.

{"success": "true"}

This will delete the current session from the coolsignup server. It won’t be possible to use this authToken any longer. It’s now useless and you should delete it from the client side (cookie or local storage).

Using the user account once logged in¶

Once logged in, you can use the authToken, to:

retrieve the user id¶

curl -X POST /api/get-user-id -d '{
    "authToken": "bmbfVLnt95S33IY6...MjaPTuZmjdWmpAQ-QA8OStz"
}'

{
    "success": true,
    "_id": "5cfae1ae7be455eeb9580c9c"
}

You can now use this _id to uniquely identify the user in your application. You can, for example, query or modify the user account in MongoDB using this _id. User accounts are stored in MongoDB in the coolsignup database, in the accounts collection. But you’re not forced to use MongoDB. You can use this _id to feed another database, using, say, MySQL, if you want.

retrieve fields about the user¶

curl -X POST /api/get-user-fields -d '{
    "authToken": "bmbfVLnt95S33IY6...MjaPTuZmjdWmpAQ-QA8OStz",
    "fields": ["screenName", "email", "_id"]
}'

{
    "success": true,
    "user": {
        "screenName": "Mauricio",
        "email": "mauricio@example.com",
        "_id": "5cfae1ae7be455eeb9580c9c"
    }
}

Then for example, use the user id to deal with resources owned by your user in your application.

Note: apart from the “_id”, “email” and “emailLower” fields, other fields you can access using /api/get-user-fields are stored in the “fields” subdocument of the user document in the MongoDB database. This is something you should know if you intend to use MongoDB requests directly.

set a user’s fields¶

curl -X POST /api/set-user-fields -d '{
    "authToken": "bmbfVLnt95S33IY6...MjaPTuZmjdWmpAQ-QA8OStz",
    "set": {"screenName": "Pascal", "favoriteColor": "yellow"}
}'

You get

{"success": true}

or

{"success": false, "error": "invalid authToken"}

For more complex modification of a user account, you might want to retrieve the user’s _id and then modify the user using direct requests to the MongoDB backend. Users are stored in the “accounts” collection of the “coolsignup” database.

Note: when using /api/set-user-fields, you’re not allowed to modify the “_id”, “email” and “emailLower” fields. Also, fields other than “_id”, “email” and “emailLower” that you can access are actually stored in the “fields” subdocument of the user document in the MongoDB database. This is something you should know if you intend to use MongoDB requests directly.

Password reset¶

Sometimes the user is stupid: they forget their password. Of course, it’s not their fault if they are stupid so we have to provide them with a way of setting a new password. There are three steps to do this.

1. Send the “reset password” code¶

curl -X POST /api/email/send-reset-password-code?lang=fr
     -d '{"email": "user@example.com"}'

This is going to send an email to the stupid user. This email will contain a link for him to reset his password.

The response to this request will be:

{"success": "true"}

unless the email doesn’t belong to a registered user. Then you’ll get

{"success": "false", "error": "no such email in the database"}

2. Check the “reset password” code¶

So your stupid user received their password reset code in their mail box, in the form of a link that looks like:

https://auth.mysite.org/code/Eqtp1kNZeNNmSan2MxOXhLhMuc

Now are they smart enough to follow that link without screwing up?

You can check this by doing a POST request to the following url:

curl -X POST /api/email/check-reset-password-code
     -d '{"code": "Eqtp1kNZeNNmSan2MxOXhLhMuc"}'

This will check if the code is a valid “reset password” code. Hopefully you’ll get

{"success": true}

If the code is not a valid code however, you’ll get:

{"success": false, "error": "Invalid reset password link"}

3. Actually reset the password¶

Extract the “reset password” code from the url at step 1. It looks like this: Eqtp1kNZeNNmSan2MxOXhLhMuc. Then post:

curl -X POST /api/email/reset-password '{
    "resetPasswordCode": "Eqtp1kNZeNNmSan2MxOXhLhMuc",
    "newPassword": "my new password"
}'

The password of the corresponding account has been succesfully reset:

{"success": true}

Unless something went wrong:

{"success": false, "error": "Password too easy to guess."}

Users changing their email addresses¶

Sometimes users want to change their email address. Users need to be logged in to do that. That is, you need to have a valid authToken. The email change is done in three steps:

1. First check the new email address¶

curl -X POST /api/email/send-change-email-code '{
    "authToken": "bmbfVLnt95S33IY6...MjaPTuZmjdWmpAQ-QA8OStz",
    "newEmail": "bobby@example.com"
}'

This will send a “change email” link to your user at the new email address. This link will look like this:

https://auth.mysite.org/code/Eqtp1kNZeNNmSan2MxOXhLhMuc

2. Check the code for copy/paste errors¶

When your user clicks the link, you check if the code is valid, to inform them in case they failed to copy paste the link correctly in their browser.

curl -X POST /api/email/check-change-email-code
     -d '{"code": "Eqtp1kNZeNNmSan2MxOXhLhMuc"}'

If the code is valid, you get:

{"success": true}

Otherwise:

{"success": false}

3. Actually change the email of the user¶

curl -X POST /api/email/change-email '{
    "authToken": "bmbfVLnt95S33IY6...MjaPTuZmjdWmpAQ-QA8OStz",
    "changeEmailCode": "Eqtp1kNZeNNmSan2MxOXhLhMuc"
'}

If the authToken or the changeEmailCode are invalid, you’ll get an error:

{"success": false, "error": "Authentication failure."}
{"success": false, "error": "The code was invalid."}

Otherwise it’s a success:

{"success": true}

Users changing their password¶

Maybe a user got suspicious after realizing their cat was observing them typing on the keyboard. They want to change their password.

This action requires a valid authToken and the current password.

curl -X POST /api/email/change-password '{
    "authToken": "bmbfVLnt95S33IY6...MjaPTuZmjdWmpAQ-QA8OStz",
    "currentPassword": "my current password",
    "newPassword": "my new password"
}

You should get the following response from coolsignup:

{"success": true}

unless something went wrong. For example if the new password supplied wasn’t strong enough, you’ll get:

{"success": false, "error": "The new password is too easy to guess"}

Deactivate an account¶

If a user did silly things, you can punish them by deactivating their account. They won’t be able to login anymore.

curl -X POST /api/deactivate-user '{"_id": "347C983638B376343"}'

Delete an account¶

To delete a user account user the user’s _id:

curl -X POST /api/delete-user '{"_id": "347C983638B376343"}'

If you want to give the opportunity to a user to delete their own account, first retrieve the user’s _id by calling

curl -X POST /api/get-user-fields '{
    "authToken": "bmbfVLnt95S33IY6...MjaPTuZmjdWmpAQ-QA8OStz",
    "fields": ["_id"]
}"

Then make a POST request to the /api/delete-user url sending the _id you just retrieved.