Custom 0Auth - Detailed API Flows

LoginTap is set up much like any other 0Auth service (like login with Google or Facebook).

Just 2 required API methods (marked red ↓↓↓) and 4 optional (marked yellow ↓↓) allow for over 10 use schemas.

Choose "Authentication modes" with one click (marked green ↓↓↓) and see exact API flow for each mode. Add your callback URL (marked blue ↓↓↓) to receive auth results without using an extra API call. Copy your unique API URL (marked purple ↓↓↓) - if you use our Postman collection.
DOWNLOAD POSTMAN API COLLECTION FOR:

Each collection features same methods, but is pre-set with options and required fields for each auth type/flow. Download and plug in your API URL marked purple ↑↑↑.
- OR - DOWNLOAD PHP 7+ LIBRARY FOR:
- OR - VIEW AN API FLOW FOR:
Start with Create Users below (it changes a bit for different auth modes API flows),
or jump to:
- Request User Auth (also changes a bit between flows)
- Get Auth Results (same for all flows)
- Get User Info (same for all flows).
- Update User (same for all flows)


Create Users

Use the POST {{url}}/api/v1/user API call with:

Key=Values:
- enabled = 1
- applicationUUID = {{application ID from your Logintap account}}
- webAuthnConfirm = 1

Optional Key=Value:
- customUUID = {{your own unique user ID}}, to make integration easier use your own userIDs for all methods, but give preference to alphanumeric hashed ID, not to emails and phone numbers.

Use the POST {{url}}/api/v1/user API call with:

Key=Values:
- enabled = 1
- applicationUUID = {{application ID from your Logintap account}}


Optional Key=Value:
- customUUID = {{your own unique user ID}}, to make integration easier use your own userIDs for all methods, but give preference to alphanumeric hashed ID, not to emails and phone numbers.

Also PLEASE MAKE SURE THAT "AUTH MODE" MATCHES API CALLS and turn on the following "Auth Mode" for the Project's settings:
In the response ↑ you get the following attributes for the object:

- id - integer - is an incremental counter of your users and is not required for any further operations;
- uuid - varchar255 - the same as userUUID - a Universal User Identifier generated by Logintap is required for user auth requests, BUT can be substituted with the optional customUUID, if you want to use your own ID instead or recording ours);
- regURL - varchar255 - an address where you need to forward users to create/register a new biometric ID for them, so it is EXTREMELY IMPORTANT that you only send this link to users you 100% know, for example to users in your secured area, or as SMS/TXT of mobile device and so no;
- sessionUUID - varchar255 - you can check if user has already connected biometry via this session in /v1/logintap/loginresult (on "loginState=1", as described in Get Auth Results below), or by /v1/getuser (on "webAuthnStatus = true", as described in Get User Info below);
- tokenUUID - varchar255 - you may use this token to double check the response of the v1/logintap/loginresult.

In the response ↑ you get the following attributes for the object:

- id - integer - is an incremental counter of your users and is not required for any further operations
- uuid - varchar255 - the same as userUUID - a Universal User Identifier generated by Logintap is required for user auth requests, BUT can be substituted with the optional customUUID, if you want to use your own ID instead or recording ours);
- *messenger name* links - varchar255 - a separate link for each messenger to send users to for creating a bot connection

- commonLink
- IMPORTANT - the common link contains a built-in mobile messaging channel selection interface, so if you do not want to bother managing bot links and render your own interface for that, just forward users to the commonLink (directly on mobiles and render QR codes with the link on desktops)
- commonShortLink - same as above to use for texting and manual typing purposes

YOU DO NOT NEED TO REFRESH BOT LINKS (NOTE 2 below) - IF YOU USE commonLinks, as it is already taken care of in our own messaging selection interface.

NOTE 1 - Biometric authentication tokens are created here, so make sure you provide this link to known and verified users ONLY, for example after they passed your usual login/password, or in SMS/TXT to their known phone numbers.

NOTE 2 - you can transform these links into QR when you want to auth users on desktops with their smartphones^ however if you do not - no worries, our system will show the QR code on its own if user opens on a desktop

NOTE 3 - if you are using biometric auth for mobile apps and website it is best to open this regURLs in iFrame inside of your existing UI, to keep the UX flow as simple as possible for users.


NOTE - you need to transform messenger URLs into QR codes when you want to auth users on desktops with their smartphones, as these links lead directly into each messenger.


NOTE 2 - (not needed when using "commonLinks") - the "shortlinks" expire exactly 120 seconds after creation, so use the following method to update the links:

POST {{url}}/api/v1/refsbots/add

Where key=values are:

- userUUID = {{from the "user" method above}} - the UUID received from user creation
↑or↓
- customUUID = {{your own unique user ID}}, if you use this option in user creation method above

- applicationUUID = {{application ID from your Logintap account}}

On the sample below we get new messenger links by using the userUUID:
- regShortUrl - varchar255 - same as above regURL, but shortened so you can insert it into SMS/TXT, email messages, and other places where it matters. Note that it uses our own AUT.HK address (stands for "auth key"). You can send users this short URL with or without HTTPS:// for even shorter SMS size.

Request User Auth

Use the POST {{url}}/api/v1/logintap/loginrequest API call with 3 parameters for the Biometry Only type of auth:

- userUUID = {{from the "user" method above}} - the UUID received from the new user creation method above
↑or↓
- customUUID = {{your own unique user ID}}, if you use this option in user creation method above.

- applicationUUID = {{application ID from your Logintap account}}, appUUID key can also be used

- webAuthnConfirm = 9, which requests biometric auth only
Use the POST {{url}}/api/v1/logintap/loginrequest API call with 3 parameters for the Biometry+Messengers auth:

- userUUID = {{from the "user" method above}} - the UUID received from the new user creation method above
↑or↓
- customUUID = {{your own unique user ID}}, if you use this option in user creation method above.

- applicationUUID = {{application ID from your Logintap account}}, appUUID key can also be used

- webAuthnConfirm = 1, which activates biometry check when pressing "YES" button in a messenger of choice
Use the POST {{url}}/api/v1/logintap/loginrequest API call with 3 parameters for the Messengers Only auth:

- userUUID = {{from the "user" method above}} - the UUID received from the new user creation method above
↑or↓
- customUUID = {{your own unique user ID}}, if you use this option in user creation method above.

- applicationUUID = {{application ID from your Logintap account}}, appUUID key can also be used

In the response you get the following data:

sessionUUID - varchar255 - is a unique identifier of the new auth session
tokenUUID - varchar255 - a unique security token of the session
channel - varchar255 - you can ignore this, as it shows that no Logintap auth delivery channels, like messengers, exist for the user
warning - varchar255 - should be empty if all is ok, an example would be a notification that your plan is over limit (auth will still happen)
webAuthnState - integer = 1 means the objectUUID user has biometry previously connected; = 0 - no biometry was yet connected
loginURL - varchar255 - an address to send users to VERIFY their biometry. IMPORTANT - If the user has "webAuthnState"=0 you will get back "regURL" instead of "loginURL", to register biometry without looking for the user in DBs, so please make sure you only allow using "regURL" for your known users, out of your secure area. The name change is designed to make sure you notice the difference and allow the "regURL" from secure area only!
loginShortUrl - varchar255 - same as above, for places where you need a short link
NOTE 1 - if you are using biometric auth for mobile apps and website it is best to open this regURLs in iFrame inside of your existing UI, to keep the UX flow as simple as possible for users

NOTE 2 - you can transform this URLs into QRs when user is starting on desktop for design purposes, or you can just let them open URLs and they will see a QR generated by our system if on desktop

In the response you get the following data:

sessionUUID - varchar255 - is a unique identifier of the new auth session
tokenUUID - varchar255 - a unique security token of the session
channel - varchar255 - you can ignore this, as it shows that no Logintap auth delivery channels, like messengers, exist for the user
warning - varchar255 - should be empty if all is ok, an example would be a notification that your plan is over limit (auth will still happen)
webAuthnState - integer = 1 means the objectUUID user has biometry previously connected; = 0 - no biometry was yet connected (you need to set user to connect it from your protected area, before you can authenticate with it)

In the response you get the following data:

sessionUUID - varchar255 - is a unique identifier of the new auth session
tokenUUID - varchar255 - a unique security token of the session
channel - varchar255 - you can ignore this, as it shows that no Logintap auth delivery channels, like messengers, exist for the user
warning - varchar255 - should be empty if all is ok, an example would be a notification that your plan is over limit (auth will still happen)

Get User Auth Result (unchanged for all API flows)

You have 2 options here: API call, or a webhook.

It is always advised to register a call back url in Logintap's project settings and receive webhooks. However if thats not technically feasible, you can use the following API call -

POST {{url}}/api/v1/logintap/loginresult with 2 parameters:
- sessionUUID - varchar255 - is a unique identifier of the new auth session, which you received from any of the APIs above
- applicaitonUUID - varchar255 - an ID of you project within your Logintap account

Both, webhook and API response, get the same data set:

sessionUUID - is a unique identifier of the auth session
tokenUUID - a unique security token of the session
userUUID - a unique identifier of the object/user
loginState = null, or 0 (zero), or 1 - shows if user has passed (=1), failed (=0), or did not finish (null) auth on the device.


COMPARE data received by "loginresult" or "webhook" of the call-back received with UUIDs from the earlier "loginrequest" API call.

If all UUID records match and "loginstate" = 1, you can allow the user to enter.
If any of this is not true - login should be forbidden.
Get User Info (unchanged for all API flows)

You can overview status of each of your users:

POST {{url}}/api/v1/getuser with 2 parameters:

- applicaitonUUID - varchar255 -
an ID of you project within your Logintap account

- userUUID = {{from the "user" method above}} - the UUID received from the new user creation method above
↑or↓
- customUUID = {{your unique user ID}}, if you use this option in user creation method above.

In response you will get:

ID - incremental user ID in this Project (Application) of your account
all the Dates - when user was created, modified or last shows which message delivery channels were connected by the user
*name*Channel, chromePush, - shows which message delivery channels were connected by the user
channel - shows which channel was last used and is set as priority for the user
Timezone - user's last known timezone
email and mobile - if user has this data (depends on how you user Logintap)
customUUID - if you use your own Custom ID to work with this user
languageuser - to which language is Logintap interface auto adjusts for this user
countRequests - all time counter of logins for this user
webAuthnStatus = "true", if user has already connected biometry for this Project/Application
uuid - Logintap generated userUUID

Update User Data (unchanged for all API flows)

You can update data fields for your users:

PUT {{url}}/api/v1/user with parameters:

required:
- userUUID = {{from the "user" method above}} - the UUID received from the new user creation method above

optional:
- Enabled = 1 or 0, to enable or disable the user
- email = {alphanumeric}, to add or update an email for the user, if needed
- phone = {alphanumeric}, to add or update a mobile phone number the user, if needed
- customUUID = {alphanumeric}, to add or update a custom ID for the user, if needed

In response you get all the same user fields, as with "getuser" above, but updated with new data.