Allow users to enter without passwords!
All Internet offedrings ... a SaaS application, desktop application, mobile app, etc. can benefit from our system!
Last updated
All Internet offedrings ... a SaaS application, desktop application, mobile app, etc. can benefit from our system!
Last updated
This topic is only for those who are merchants. If you are a regular user -- i.e. one who uses our special inbox as a user only, then this topic is not for you.
The word "you" here indicates you as a merchant i.e. the person who is using our API The word "offering" means whatever SaaS/Software/Application/App etc where you allow entry of users from known.email
Introduction If you are coding your own offerings, integrating the API from Known.Email is very easy. It is quite easy if you are offering someone else's code too -- we have a separate topic on that. In either case, reading this particular topic is mandatory. Also, before you read this topic you must have finished reading and understanding the previous topic.
Video Tutorial
Preparation Here is a demo of the extremely simple API that we have: https://known.email/api/testapi.php Play around with it and you will notice that you are able to send both regular messages as well as encrypted ones.
At the end of that page; there is a link which will reveal the entire PHP source code for you. You can suitably modify it as per your needs and use it at your own server.
There are after all just 3 API calls that you need to learn (and an optional 4th one, if you want to use our API to do the PGP encryption. Not recommended, but it can save you coding time) Even if you are NOT using PHP -- it should be quite easy for you to understand how we use the API calls. As indicated before, they are simple REST calls, using the "POST" method. Make sure that your code is hosted at the a server whose IP address was used to register the domain; when you used the "MakeMerchant" command to configure your account.
You can also check this demo "merchant" site and check for yourself indeed an encrypted OTP does get sent to you when you are user: https://demo.known.email
Strategy for a new SaaS/application/app you want to create
Create a entry HTML page at your domain website with just one input box. Ask user to enter their alias they had created at Known.Email Make sure you give a link to https://known.email/reg so that the user can create an account with us; if they don't have one.
Once the user enters the alias, make an API call to our system to retrieve the user's public PGP key. This will also check if that user exists in our system or not. If indeed the user is in our system; you will get a unique ID (UID) which is guaranteed to be the same for the same user at your domain. If the user is NOT in our system (i.e. the alias was wrong) then you would get an error message.
If the user did exist (i.e. the alias was valid), you will get the following JSON object:
{
"msg":"hello",
"userid":"rearerereerwerwer",
"origin":1,
"data":"PUBLIC KEY",
"success":true,
"errtype":0,
"freekoyns":0,
"paidkoyns":111
}
IMPORTANT: You should never store the alias that the user gave when entering your system, as a form of identifying the user. Instead you should use the userid that is returned in this object. The user is free to change his alias anytime! But the userid of that user will never change!
In the above JSON object; the "origin" field can be useful to you. It gives the code for the method used
by the user to originally get his account. As you may know; you can become a member at known.email in several different ways (5 on last count. More are being added) But as a merchant; you may decide that you would ONLY allow those users of known.email who had registered (as an example) only using Telegram. In that case, you should check if the origin has a value of 1 -- for that is the code for those who got an account using Telegram. But some merchants may ignore this origin field as they may not mind if one person takes up multiple accounts.
If the user had saved his public PGP key at his account at Known.Email; you would get it in the "data" field in the above JSON. Or you would get a URI to that Public key (in the same "data" field) -- in which case, retrieve it from that indicated URI. Either way, your code would obtain the PGP public key of the user. It is possible that the user has forgotten to save the public PGP key. In such a case, you should exit the rest of the steps gracefully with a message asking the user to follow the steps to save his public PGP key from the special inbox page we have given him. The link is always: https://inbox.known.email
Once your code has located the public PGP key of the user, the code should now proceed to generate a one time use password (OTP) for that user. If the user was NOT part of known.email, you should give some helpful instruction and end the process. We have written a separate topic on how to craft such an OTP. Read that for ideas.
Use the user's PGP public key and encrypt the OTP. This is done using the GPG utility via the bash command line (in Linux) or some other means -- most programming languages have a module to do the GPG encryption using the PGP public key. If you do not have such a code, you can make a system call to a sample Linux bash script which we have given in the testapi.php source code. If nothing works, you can use our helper API (seen in the testjson.php code) to do the encryption via REST https call. But if you use that last method please be noted that the encryption is being done at our end -- which means your super-secret OTP can theoretically get exposed to us. Though we do not monitor that helper API at all, it is our duty to inform you.
Craft a useful subject line; and that encrypted OTP message becomes the "body". Send both to the user using our API to send an encrypted message to that user who had given the alias.
At this point the entry page would change. The new can have an input box for where the OTP has to be entered by the user (or there is an alternative -- see below) Your HTML page will now have to wait. If you want; you can set a timeout on that page... for example; if you had crafted the OTP to expire after some timeout. Alternatively, you can just show a message (instead of an OTP input box) asking the user to click on a link that would be in the encrypted email. In that case, it is not the plain OTP that would be in the encrypted message; but a properly crafted HTML link (using the <a> tag) which has the OTP buried in the query_string of the href of that link.
Note that the user may be doing the clicking of the HTML link stated in previous step; on one device which may NOT BE THE SAME as the device where the user is actually entering your offering! So your code should be able to accommodate all such possibilities.
At this stage; we assume that the user has indeed either clicked on the OTP link; or supplied the OTP into the input box at the waiting page. And your code is convinced that the OTP was correct. It is at this point you need to check your own database and either create a new user (if that person was using your offering for the first time i.e. it is a sign-up aka registration ) OR if that person was previously already a user of your offering -- in which case the entry would be regarded as a sign-in aka login
Now at this stage, it is up to you to decide what happens to the user. If the user is a new one (i.e. it was a sign-up) then your code will go in one direction. But if it was a sign-in then the code would take a different route. How those two routes would work out is totally upto your offering you are providing. It is your intellectual property from this point onward.
If you notice carefully, we have suggested a workflow where the user carries out exactly the same steps whether he was using it for the first time (i.e. for sign-up at your offering) OR if he was a repeat user (i.e. it was a login) This is deliberate: ALL user ends up getting the SAME smooth, friction-less user experience! Be it a first time user who came to use your solution -- or one who had already become your user!