NAV
CSharp Shell Javascript

Introduction

Welcome to the Encrypxon 2FA API! You can use our API to add 2FA into your web application.

We have language bindings in Shell, javascript and C# with more to come!

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

How the 2FA process works

The enrollment process works by notifying the Encrypxon app on the device to be used as the customers 2FA device that an enrollment request has been generated.

The QRCode that is scanned by the users device has a unique identifier for the enrollment. When the QRCode is scanned, the device generates a new key pair to encrypt the data used later in the 2FA authentication process. The public key of this key pair is sent to the Encrypxon server along with unique enrollment code. The private key is held in secure storage in the customers device. It never leaves the device.

Using this mechanism of scanning a QRCode ensures that the user has the phone in proximity of your web application during the enrollment process.

When a 2FA is requested by your application, the Encrypxon server sends some entropy encrypted with the public key of the users device, generated during the enrollment process. The device can decrypt this entropy using its private key. The decrypted entropy is sent back to the Encrypxon server and compared with the entropy sent to the device. If this matches then the 2FA is successful and your application can be notified that the user should be allowed to log in.

A separate key pair is generated on the device for every website using the Encrypxon 2FA process.

Every 2FA request is stored on the Encrypxon server for audit purposes.

API Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://api.encrypxon.com"
  -H "X-API-Key: YourApiKey"
const kittn = require('kittn');

let api = kittn.authorize('meowmeowmeow');
var config = new EncrypxonClientConfiguration {ApiKey = "YourApiKey"};
var client = new Encrypxon2FaClient(config);

Make sure to replace YourApiKey with your API key.

Encrypxon uses API keys to allow access to the API. You can get a new Encrypxon API key by emailing us at developer support.

Encrypxon expects for the API key to be included in all API requests to the server in a header that looks like the following:

X_API_Key: YourApiKey

Enroll

Enroll a user in 2FA

var config = new EncrypxonClientConfiguration {ApiKey = "YourApiKey"};
var client = new Encrypxon2FaClient(config);
var body = new EnrollRequest {Emaiil = "customerEmail"};
var res = await client.Enroll2faAsync();
var qrcodeImageBase64Encoded = res.Result.Result.QrCode;

The request body should be

{
    "email": "useremail@somedomain.com"
}

The above command returns JSON structured like this:

{
  "isError" : false,
  "message" : "Success",
  "exceptionMessage" : "some message about what went wrong",
  "result" : {
    "qrcode" : "base64 encoded string"
  }
}

This endpoint enrolls a user in 2FA.

The request tells Encrypxon the customer identifier.

The response provides a QRCode in a base64 encoded string. This should be displayed to your user.

You can use the following html to display the decoded image.

<img src="data:image/jpeg;base64, {the base64 encoded data}]">

You application should inform the user to open the Encrypxon app on their phone and go to the Enroll 2FA menu option. Here they must scan the QRCode. Once done they are enrolled as a 2FA user.

HTTP Request

POST http://api.encrypxon.com/2fa/enroll

The request body contains a single parameter which is the identifier of the customer to be enrolled.

Enrolled

Check whether a user is enrolled in 2FA

var config = new EncrypxonClientConfiguration {ApiKey = "YourApiKey"};
var client = new Encrypxon2FaClient(config);
var res = await client.GetEnrolledAsync();
bool enrolled = res.Result.Result;

The above command returns JSON structured like this:

{
  "isError" : false,
  "message" : "Success",
  "exceptionMessage" : "some message about what went wrong",
  "result" : true
}

This endpoint tests whether or not a user is enrolled in 2FA.

The result is true if the user is enrolled or false otherwise.

You should use this during the login process to decide whether or not to start a 2FA authorisation or not.

Addiitionally you might want to use this method to decide whether or not to offer enrollment in the users profile page in your website.

HTTP Request

POST http://api.encrypxon.com/2fa/enrolled?userId={customerId}

URL Parameters

Parameter Description
userId The ID of the customer to check enrollment status for

Authenticate

These methods are used to use 2FA to authenticate a user.

Start 2FA authentication

var config = new EncrypxonClientConfiguration {ApiKey = "YourApiKey"};
var client = new Encrypxon2FaClient(config);
var body = new Start2FaRequest { Email = "customerEmail"}
var res = await client.Start2FaAuthenticationAsync(body);
string requestId = res.Result.Result;

The request body should be

{
    "email": "useremail@somedomain.com"
}

The above command returns JSON structured like this:

{
  "isError" : false,
  "message" : "Success",
  "exceptionMessage" : "some message about what went wrong",
  "result" : "requestId"
}

This endpoint starts the 2FA authentication process for a user. You shoudl tell the user to open the Encrypxon app and go to the Authorise 2FA menu option. Here they will click on the item for your website, indicated by your favicon and domain name.

When they click on this the app will negotiate the 2FA request with the Encrypxon server and if this is the users enrolled device the 2FA authentication will be confirmed.

HTTP Request

POST http://api.encrypxon.com/2fa/Initiate2Fa

The request body contains a single parameter which is the identifier of the customer to be enrolled.

HTTP Response

The reponse provides a unique request ID that is used in the endpoint which checks if the authorisation has been successful.

Check 2FA authentication status

var config = new EncrypxonClientConfiguration {ApiKey = "YourApiKey"};
var client = new Encrypxon2FaClient(config);
var res = await client.Get2FaAuthorisationStateAsync(secondFactorId);
bool auth = res.Result.Result;

The above command returns JSON structured like this:

{
  "isError" : false,
  "message" : "Success",
  "exceptionMessage" : "some message about what went wrong",
  "result" : true
}

This endpoint tests whether or not a user has successfully responded to the 2FA authorisation.

The result is true if the user is enrolled or false otherwise.

The parameter required is the ID returned in the Start 2FA Authentication call.

HTTP Request

POST http://api.encrypxon.com/2fa/Authorisation?secondFactorId={requestId}

Errors

The Encrypxon 2FA API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
404 Not Found – The path you specified does not exist
405 Method Not Allowed – You tried to use invalid method
406 Not Acceptable – You requested a format that isn’t json
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintenance. Please try again later.