Gozar API

Gozar APIs is a set of HTTP API that you could call to use the Gozar App for your users. These APIs are pure HTTP GET functions that you may call from any programming language with no particular library or prerequisites. Gozar has only three comprehensive, yet straightforward functions that we explain in detail.

The Gozar API address is api.gozar.io, and you may call it or open it in a browser to see the current API version as a JSON object. Furthermore, the API test web page is gozar.io/api/test.html that you may use it as a sample code or test your input parameters.

To use Gozar App for your users, you must have a contract. A contract has two limitations; the maximum number of users and the validity period. For example, a contract may have 1000 users for one year. When you open a contract, we create an jwt (JSON Web Token) for your contract too. In all API calls, you must pass your JWT as an HTTP request header parameter, like this:

var xmlHttp = new XMLHttpRequest();
xmlHttp.setRequestHeader("Authorization", "Bearer " + jwt);

Add

This function adds a user to Gozar with the following syntax, and the return value is a JSON object.

https://api.gozar.io/add?userId=[userId]&email=[email]&phone=[phone]&phoneOverwrite=[true/false]

{
  "result": "successful",
  "link": "[url]"
}

{
  "result": "error",
  "reason": "[reason]"
}

userId is a unique key that you assign to your user and store it in your database. You may use an existing username of your user as userID; however, we highly recommend avoiding it. Gozar supports blind authentication, which means Gozar does not require your real username for authentication, and it is not a good security practice to use username instead of blind userId.

If you send a new userId, Gozar adds it as a new user and increments your contract user count. If it is an existing userId, Gozar updates the previous one without any update in your contract.

email is an optional parameter. If you pass the user's email address, Gozar sends the registration link to the user's email address and does not return link field.

phone is an optional parameter. If you pass the user's mobile phone number, Gozar sends the registration link to the user's smartphone by SMS and does not return link field. If email parameter has been sent, Gozar ignores phone parameter.

phoneOverwrite is an optional parameter. If you pass the user's mobile phone number, this parameter indicates that if Gozar can overwrite the previous phone. If this parameter is set to false and the passed phone is not equal to the previous phone, Gozar returns phoneOverwrite error.

If the Add function is successful, it returns a URL link. You may use this link to redirect the user to install the Gozar App. If the user opens this link on a smartphone, it redirects to the Google Play Store or Apple App Store of the Gozar App. Otherwise, if the user opens this link on a computer, it displays a QR code. If the user did not install Gozar App yet and scans the QR code with the smartphone camera, it redirects to the Gozar App page at Google Play Store or Apple App Store. If the user has Gozar App and scans the QR code with Gozar App, it opens a menu to enroll the user on Gozar. The QR code is valid for 5 minutes, and if it expires, you can call the Add function with the same userId to get a new QR code. You could also extract the QR code from the link and display it on your page. The QR code is in qrcode query param with base64 format.

If the result of the Add function is an error, then the reason explains the error. The reason can be one of the followings: invalidInput, invalidContract, disabledContract, maxUsers, failedEmail, failedSMS, phoneOverwrite and unknown.

// Add function sample code

// create an HTTP GET query
var jwt =
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250cmFjdCI6InNhbXBsZSIsImlhdCI6MTYwNTMwNDI4Nn0.g4D0xCSDn9Zl6DDQdTu4r7JUEWiq5ejISdXKS8OVrq8";
var userId = "john";
var query = "https://api.gozar.io/add?" + "userId=" + userId;

// submit the query
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", query);
xmlHttp.setRequestHeader("Authorization", "Bearer " + jwt);
xmlHttp.send();

// get the HTTP response
xmlHttp.onreadystatechange = function () {
  if (xmlHttp.readyState == 4 && xmlHttp.status == 200) {
    var responseJson = JSON.parse(xmlHttp.responseText);
    if (responseJson.result == "successful") {
      var link = responseJson.link;
      var qrcodeIndex = link.indexOf("qrcode=") + "qrcode=".length;
      var qrcode = link.substring(qrcodeIndex);
      console.log("link:", link);
      console.log("qrcode:", qrcode);
    } else {
      console.log("error:", responseJson.reason);
    }
  }
};

You can find the complete source code at gozar.io/api/test.html.

Remove

This function removes a user from Gozar with the following syntax, and the return value is a JSON object.

https://api.gozar.io/remove?userId=[userId]

{
  "result": "successful"
}

{
  "result": "error",
  "reason": "[reason]"
}

Removing a user decrements one user count from your contract. If the result of the Remove function is successful, there is no more info. If the result is an error, then the reason explains the error. The reason can be one of the followings: invalidInput, invalidContract, disabledContract, userNotFound and unknown.

// Remove function sample code

// create an HTTP GET query
var jwt =
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250cmFjdCI6InNhbXBsZSIsImlhdCI6MTYwNTMwNDI4Nn0.g4D0xCSDn9Zl6DDQdTu4r7JUEWiq5ejISdXKS8OVrq8";
var userId = "john";
var query = "https://api.gozar.io/remove?" + "userId=" + userId;

// submit the query
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", query);
xmlHttp.setRequestHeader("Authorization", "Bearer " + jwt);
xmlHttp.send();

// get the HTTP response
xmlHttp.onreadystatechange = function () {
  if (xmlHttp.readyState == 4 && xmlHttp.status == 200) {
    var responseJson = JSON.parse(xmlHttp.responseText);
    if (responseJson.result == "successful") {
      console.log("removed");
    } else {
      console.log("error:", responseJson.reason);
    }
  }
};

You can find the complete source code at gozar.io/api/test.html.

Enable

This function enable or disable a user in Gozar with the following syntax, and the return value is a JSON object.

https://api.gozar.io/enable?userId=[userId]&enable=[true/false]

{
  "result": "successful"
}

{
  "result": "error",
  "reason": "[reason]"
}

You can enable or disable Gozar multi-factor authentication for a user with Enable. In this case, the Authenticate function returns successful without sending notification and authentication. This feature is useful when the user's smartphone is not available temporarily when for example it is broken. You may disable a user for one day and enable it again. If the result of the Enable function is successful, there is no more info. If the result is an error, then the reason explains the error. The reason can be one of the followings: invalidInput, invalidContract, disabledContract, userNotFound and unknown.

// Enable function sample code

// create an HTTP GET query
var jwt =
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250cmFjdCI6InNhbXBsZSIsImlhdCI6MTYwNTMwNDI4Nn0.g4D0xCSDn9Zl6DDQdTu4r7JUEWiq5ejISdXKS8OVrq8";
var userId = "john";
var query =
  "https://api.gozar.io/enable?" + "userId=" + userId + "&enable=false";

// submit the query
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", query);
xmlHttp.setRequestHeader("Authorization", "Bearer " + jwt);
xmlHttp.send();

// get the HTTP response
xmlHttp.onreadystatechange = function () {
  if (xmlHttp.readyState == 4 && xmlHttp.status == 200) {
    var responseJson = JSON.parse(xmlHttp.responseText);
    if (responseJson.result == "successful") {
      console.log("disabled");
    } else {
      console.log("error:", responseJson.reason);
    }
  }
};

You can find the complete source code at gozar.io/api/test.html.

IsUserReady

This function checks the status of a user with the following syntax, and the return value is a JSON object.

https://api.gozar.io/isuserready?userId=[userId]

{
  "result": "successful"
}

{
  "result": "error",
  "reason": "[reason]"
}

If the user is ready to authenticate the result of the IsUserReady function is successful, there is no more info. If the user is not ready or there is an error the result set to error and the reason explains the error. The reason can be one of the followings: invalidInput, invalidContract, disabledContract, userNotFound, userNotEnrolled and unknown.

// IsUserReady function sample code

// create an HTTP GET query
var jwt =
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250cmFjdCI6InNhbXBsZSIsImlhdCI6MTYwNTMwNDI4Nn0.g4D0xCSDn9Zl6DDQdTu4r7JUEWiq5ejISdXKS8OVrq8";
var userId = "john";
var query = "https://api.gozar.io/isuserready?" + "userId=" + userId;

// submit the query
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", query);
xmlHttp.setRequestHeader("Authorization", "Bearer " + jwt);
xmlHttp.send();

// get the HTTP response
xmlHttp.onreadystatechange = function () {
  if (xmlHttp.readyState == 4 && xmlHttp.status == 200) {
    var responseJson = JSON.parse(xmlHttp.responseText);
    if (responseJson.result == "successful") {
      console.log("ready");
    } else {
      console.log("error:", responseJson.reason);
    }
  }
};

You can find the complete source code at gozar.io/api/test.html.

Authenticate

This function authenticates a user with his/her smartphone with the following syntax, and the return value is a JSON object.

https://api.gozar.io/authenticate?userId=[userId]&text=[text]

{
  "result": "successful",
  "biometric": "[yes/no]"
}

{
  "result": "error",
  "reason": "[reason]"
}

text is the message that Gozar App displays to the user on the smartphone. This field is optional and if it is not passed to the Authenticate function, Gozar uses the default message.

After calling the Authenticate function, the user gets a notification on the smartphone and may confirm it with his/her biometric feature (e.g., fingerprint, face) or unlock the smartphone and confirm it. The user has around 60 seconds to confirm push notification.

If the Authenticate function's result is successful, the biometric field indicates that the user uses biometric features like fingerprint and face to authenticate or not.

If the result is an error, then the reason explains the error. The reason can be one of the followings: invalidInput, invalidContract, disabledContract, userNotFound, userNotEnrolled, deviceNotFound, reject, timeout and unknown.

userNotEnrolled indicates that the user did not scan the QR code and enroll yet. deviceNotFound occurs when Gozar could not send a notification to the smartphone, maybe because the user has removed the Gozar App. In this situation, call the Add function for this user to get a new QR code and enroll again.

If the user is disabled, the Authenticate function returns successful without sending notification and authentication. You may disable Gozar multi-factor authentication for a user using dashboard or Enable function.

// Authenticate function sample code

// create an HTTP GET query
var jwt =
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb250cmFjdCI6InNhbXBsZSIsImlhdCI6MTYwNTMwNDI4Nn0.g4D0xCSDn9Zl6DDQdTu4r7JUEWiq5ejISdXKS8OVrq8";
var userId = "john";
var text = "Do you want to login to Gozar website?";
var query =
  "https://api.gozar.io/Authenticate?" + "userId=" + userId + "&text=" + text;

// submit the query
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", query);
xmlHttp.setRequestHeader("Authorization", "Bearer " + jwt);
xmlHttp.send();

// get the HTTP response
xmlHttp.onreadystatechange = function () {
  if (xmlHttp.readyState == 4 && xmlHttp.status == 200) {
    var responseJson = JSON.parse(xmlHttp.responseText);
    if (responseJson.result == "successful") {
      console.log("biometric:", responseJson.biometric);
    } else {
      console.log("error:", responseJson.reason);
    }
  }
};

You can find the complete source code at gozar.io/api/test.html.