Introduction

Welcome r to the Regzen documentation. This guide will help you easily integrate Sign in with Regzen to your website.

Setup

Step 1: Including the Library

Include the Regzen JavaScript Library libary as an NPM module or as a script tag.

If included as a script tag, a RegzenClient global object will be exposed:

Include

<!-- Include the regzen-client script using a script tag. -->
<script src="https://unpkg.com/regzen-client/dist/regzen.min.js"></script>

# Or install regzen-client as a node module.
$ npm install regzen-client --save

// And later, use it like this:
import RegzenClient from "regzen-client";

Step 2: Instantiating the Client

Instantiate the client with the application id we have provided you.

Instantiate

const regzen = new RegzenClient({
  applicationId: "YOUR_APPLICATION_ID",
});

You should add the "Sign in with Regzen" button and start the sign in process by calling the regzen.signIn method.

Usage

<div class="regzen-sign-in" onclick="regzen.signIn()"></div>

Step 4: Handling the Authorization Code

After the user has scanned the QR code and approved the authorization request using the Regzen mobile app, an authorization code will be generated. The Regzen JavaScript Library library will retrieve this authorization code and hand it to you using the regzen.onGranted event. You need to pass this authorization code to your backend and exchange it with the Regzen API in order to retrieve the user's data.

Note: This authorization code can be used only once and also expires after a short time. If it expires, you'll need to start over and get a new one.

We have libraries for various technologies which can handle the exchange communication for you:

Support for more languages is coming soon.

If there is currently no library for your language, see the Exchange Authorization Code section for information on how to do this manually.

Handle Authorization Code

regzen.onGranted(function (authorizationCode) {
  // Send the authorization code to the Regzen API.
});

Step 5: Showing the "Protected by Regzen" Alert

When one of your users chooses to sign in to your website using Regzen, you shouldn't allow them to use their password to sign in anymore. You can do this by keeping additional information about every user in your database, something like is_using_regzen and setting that to true if the user used Regzen to sign in. Regzen provides you with a convenient regzen.showProtectedAlert method to show an alert and notify your users that they should use Regzen to sign in instead of a password.

Note: You can override the styles of this alert by following the SweetAlert theming guide.

Showing Alert

function logIn() {
  // Call an endpoint on your API to check if user is using Regzen.
  const response = await fetch('https://api.yourapp.com/[email protected]');
  const user = response.json();

  if (user.is_using_regzen) {
    // Show the "Protected by Regzen" alert.
    regzen.showProtectedAlert();
  } else {
    // Call additional endpoint to log in user if he is not using Regzen.
  }
}

Using the mobile app, users can choose to no longer use Regzen to sign in to your website and revert back to using their password. Regzen will notify you of this by sending an HTTP POST request with some encrypted payload (see notes below) to your webhook URL. You can set this URL when registering your application. It is up to you to choose if you will revert your users to their old password or send them an email for resetting their password.

Note 1: The request body data is encrypted and you will have to follow the steps in the Decrypting the Response section to extract the raw data. After successful decryption, you will get a stringified JSON with the data (see on the right).

Note 2: If you're using any of Regzen libraries which can handle the exchange communication for you, you're also supplied with payload decryption function. Please refer to the official documentation of corresponding Regzen library.

Decrypted Request Body

{
  "email": "[email protected]" // Email of the user who chose to no longer use Regzen.
}

Step 7: Handling Other Events

You can provide event handlers for the following events:

Event	Parameters	Description
onDenied		Called when the user denies the authorization request.
onTimedOut		Called when the authorization request times out.
onError	error	Called when an unexpected error occurs from Regzen's side.

Event Handling

regzen.onDenied(function () {
  // Give some feedback to the user when the authorization request was denied.
});

regzen.onTimedOut(function () {
  // Give some feedback to the user when the authorization request timed out.
});

regzen.onError(function (error) {
  // Give some feedback to the user when an unexpected error occured..
});

Regzen API Endpoints

Exchange Authorization Code

Exchange authorization code generated by the Regzen API for user data.

Note: The user data is encrypted and you will have to follow the steps in the Decrypting the Response section to extract the raw data.

$ curl "https://api.regzen.com/api/oauth/exchange?authorization_code=497c4bb7f892f0b03d8a9f7c6ead70bc"

HTTP Request

GET https://api.regzen.com/api/oauth/exchange

Query Parameters

Parameter	Required	Type	Description
authorization_code	Yes	string	ex. 497c4bb7f892f0b03d8a9f7c6ead70bc

Response

Response

{
  "data": "ENCRYPTED_USER_DATA"
}

Status code	Description
200	The authorization code was exchanged for user data and the operation was successful.
403	The provided authorization code is invalid or expired.
422	The format of the provided authorization code is invalid.
500	Something went wrong while processing the request.

Decrypting the Response

Step 1: Decode the data from Base64. After decoding, your data will be in this format:

[INITIALIZATION_VECTOR][ENCRYPTED_MESSAGE_HASH][ENCRYPTED_MESSAGE]

Note: Brackets are not part of the data, they are just used to illustrate the structure of the data.

Step 2: Extract the first 16 characters for the initialization vector.

Step 3: The next 32 characters represent the hash generated by HMAC SHA-256. Generate your own hash using the same algorithm by hashing [ENCRYPTED_MESSAGE] with your application secret as the key. The hashes need to match in order to confirm the integrity of the message.

Step 4: Use something like openssl_decrypt to decrypt the [ENCRYPTED_MESSAGE] with AES-256-CBC using your application secret as the key and the data extracted in step 2 as the initialization vector.

Step 5: After successful decryption, you will get a stringified JSON with the user data.

JSON Structure

{
  "email": "[email protected]"
}