Introduction

COVR's Multi‑Factor Authentication API helps you to safely authenticate customers for logins and onboarding. It works via your own customized, single login. The REST API is a web service for developers to programmatically interact with COVR's real-time transaction authorization platform.

It has 3 layers of authentication:

  • Smartphone.
  • PIN.
  • Biometrics (a fingerprint sensor or a facial-recognition camera).


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com/identity/covr/multifactorauthentication


Conceptual model

Conceptual model


Definitions

Callback URL

The URL for the callback request.

MFA

Multi‑Factor Authentication (MFA) is an authentication method in which users are granted access only after successfully presenting 2 or more pieces of evidence (or factors) to an authentication mechanism using features like biometrics and PIN codes.

Webhook

A webhook − also called a web callback or HTTP push API − is an HTTP POST callback to your back-end service. For example, when the customer accepts a transaction request, an HTTPS POST request is sent to your specified callback URL.


API workflows

Workflow diagram


Features

  • Passwordless MFA.
  • Asymmetric encryption.


Getting started

Add transaction templates

If you want to create a transaction you need, among other things, a template ID, sometimes referred to as action ID.

It is the ID of the transaction template that defines what the end-user will see and interact with on their mobile device. For example Pending Transaction, where the end-user can either Accept or Decline the transaction.

^^JSON response from a createCompany request - excerpt^^
    "actions": [
        {
            "id": "ca9872eb-24d3-42e2-b417-18c1a6b9c2df",
            "name": "Default"
        }
    ],


^^JSON response from a createCompany request^^
{
    "id": "da658803-5630-46eb-ba90-3cdf87b2911a",
    "name": "Company Name r",
    "fullName": null,
    "dateCreated": "2020-05-08T07:36:40.1973478Z",
    "dateCreatedEpoch": 1588923400,
    "webSiteName": null,
    "webSiteURL": "www.companynamer.com",
    "logoCDNGuid": null,
    "active": true,
    "transactionsCallbackUrl": "https://www.companynamer.com/webhook",
    "companyKeyContact": {
        "id": "8124bce9-2a7b-417a-9008-0b861a707b1c",
        "fullName": "John Smith",
        "emailAddress": "emailr@companyname.com",
        "phoneNumber": "+1111111111",
        "dateCreated": "2020-05-08T07:36:40.1994405Z",
        "dateCreatedEpoch": 1588923400,
        "countryCode": 0
    },
    "publicKeys": null,
    "actions": [
        {
            "id": "ca9872eb-24d3-42e2-b417-18c1a6b9c2df",
            "name": "Default"
        }
    ],
    "isSuccess": true,
    "errorCollector": []
}


Actions refers to the action you want to send to an end-user for verification. In this API this is the Create Transaction endpoint.

Note: You can create as many actions as you wish, depending on the business workflow that you are protecting. Creating an action allows you to attach specific actions to your business workflows.

When you create or edit an action in the Admin UI you will see an example JSON payload. This is the template for the JSON requests that are consumed by the '/createTransaction' endpoint.

Input Name Description
Id This is a generated value so you can refer to a specific action in your business workflow you are protecting.
Name A name for this action so you can easily identify it in the admin panel.
Layout Currently we only support a 'simple' layout format. We are planning to expand the end-user UI templates so you can display the transaction details in various ways.
Background Image You can upload a background image that will appear behind the transaction message sent to an end-user's mobile device.
Transaction Image You can upload a transaction image that will appear inline with the transaction message sent to an end-user's mobile device.


Register end-users

Registering/onboarding users to use COVR with your service is made as simple as possible. End-users must create a connection with your service using a Quick Response (QR) code. The QR-code generated is specific to the COVR partner and the end-user requesting the connection with your service.

Once the end-user scans a QR-code from within the COVR application, a connection is established between the COVR partner and the end-user. QR-codes are regenerated every 20 seconds and the QR-code image is streamed into the imgElement specified on your website. Once the maximum amount of iterations has elapsed, the end-user must take action to restart the QR-code if they have not yet established a connection from within their mobile application.


Include JavaScript script tags

Include the following JavaScript script tags into your HTML page or server-side template. These are provided to help you integrate the required functionality as quickly as possible:

^^JavaScript script tags ^^
<script src="https://www.cdn.covrsecurity.io/scripts/signalr.min.js"></script>
<script src="https://www.cdn.covrsecurity.io/scripts/covrsecurity.min.js"></script>


Retrieve a Bearer token for QR-code requests

Note: Requests for API tokens should be executed from your server-side code and injected into the page render.

If your token type is not of qrcode then the authorization to the API will fail and an authentication token will not be returned. Once you have obtained a token you can include it in the markup.

See: Retrieve the access token for QR-code SDK


Instantiate the JavaScript object

Instantiate the JavaScript objects in the example below and configure the required settings for the QRCodeGenerator as described in the table below.


Connection requests from the end-users are sent to the webhook URL

Connection requests from end-users who scan the QR-code, will be sent to the webhook URL that you specified in the Account Settings section of the admin panel. The JSON sent with the user's connection request will have an event of type connection. Once you have processed the webhook data and saved their connection details, you can redirect users to any success pages.

Note: The webhook URL was set up during the KPN API Store onboarding process.


Examples

^^Example settings and object instantiation^^
    var settings = {
        imgEl: document.getElementById("qrImg"),
        btnEl: document.getElementById("qrBtn"),
        token: "eyJhbGciOiJSUzI1NiIsImtpZCI6IkNENjI0RTZEM0Y4REUxREJFRDFBQUU3NDdGQTE3NEVCMERDOUYzMUIiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJ6V0pPYlQtTjRkdnRHcTUwZjZGMDZ...",
        companyUserId: internalUserId,
        transactionId: guid(),
        url: data.url,
        successfulCallback: successfulCallback,
        onLoadCallback: onLoadCallback
    }

    let qrCodeGenerator = new window.CovrRegisterQrCodeGenerator(settings);


^^Callback function example^^
    function successfulCallback() {
        document.getElementById(‘covrContainer’).innerHTML = "Connection established";
    }

    function onLoadCallback(code, message) {
        switch (code) {
            case 200: {
                document.getElementById(‘covrContainer’).querySelector('span').innerHTML = "";
            }
            break;
            case 400: {
                document.getElementById(‘covrContainer’).querySelector('span').innerHTML = "Some error occured. Please, update your page";
            }
            break;
            case 401: {
                document.getElementById(‘covrContainer’).querySelector('span').innerHTML = message;
        }
        break;
        default:
            document.getElementById(‘covrContainer’).querySelector('span').innerHTML = ‘’;
        }
    }


Parameter Type Example Description
imgEl DOM Element document.getElementBy-Id("covr_qrImage") HTML Image element in your markup that will contain the QR-code PNG image returned from our servers. The image size in your page should be greater than 250px.
btnEl DOM Element document.getElementBy-Id("covr_buttton") HTML Button element that will allow deep linking so that your end-users accessing the QR-code from a mobile device can still send the data to the COVR application, without the need to scan the QR-code.
token string yJhbGc...NGNU The authorization token you've obtained from the server-side which is of type qrcode. You will need a specific API ID and secret (API keys) created with type qrcode to access the QR-code endpoint.
companyUserId string b5e30120-0bc0-4dfcaad6-7f1aba7b985e A reference to your internal user ID for the user making the connection request. It is recommended that you create a new unique ID and map this value to your actual userId so as not to expose their unique ID in your system.
transactionId string e304bcee-8ae9-4dddafc3-4e8180945aea This value is returned to your servers via the JSON POST sent to your webhook. You will need to use this transactionId to verify your user's response to adding your service as a connection.
successfulCallback function function successfulCallback() Function call triggered when there is a successful connection established in the COVR app by the end-user.
onLoadCallback function function onLoadCallback() Function call triggered when the QR-code has loaded.


Errors

If there are any errors in the settings passed into the constructor of the QrCodeGenerator, they will be outputted as errors visible in the development tools console of the browser you are testing in.


Webhook response object models


Connection responses

^^Connection JSON response^^

    {  
    "id":  "aba7fbe9-f975-4e7e-af49-56ca5e1fc812",  
    "Data":  {  
        "TransactionId":  "5a7a1350-ab3e-996a-3aaf-89fa8285edf6",  
        "CompanyUserId":  "465675664454",  
        "CovrClientId":  "100c175f-41b7-40ed-aaf0-20bafbee17a7",  
        "CompanyRegistrationPublicKey":  "J4IsSOmBHb4bBivKycSN5wBNg6pNv07pimXgcgBbJSZCLgQyqYYtFGX8DQ==",  
        "DateCreatedEpoch":  1554188858  
        },  
        "Event":  "Connection",  
        "Timestamp":  1554188858  
    }


^^Event Type : Transaction JSON response^^

    { 
    “id”: “2f90bcf5-0c92-474d-8612-3a668e049389”, 
    “data”:  { 
        “transactionId”: “35be30a9-bc34-4481-b1cf-ac54540130eb”, 
        “status”: “Rejected” 
        “Signatures”:  { 
            “CovrSignature”: “pLWsfIbvsIg1UWEBEeufM0rpcDtGq4KF86JC+lxbCKGciykrUil50RhwNMUf3L7oh10KGE29IDZoQZ3NZiY8Aw==”, 
            “CompanySignature”: “xl1ubBPlDwGg/WRsqXpJRKZTAmTbSpJIp4Wnfugid51LesETk2WolUhTnXGaOcplUbF+hya40MdP8VVZjYJ7Cg==”, 
            “ClientSignature”: “5PLEOU3eQfXvX0LxqloitNhQju1mYhz4sFClAIvCfnvalMGEz/LLjVe47I9GjGXp/yHLxht8NUSUfXN9Uk7lDQ==”, 
            “RegistrationSignature”: “J4IsSOmBHb4bBivKycSN5wBNFRpTdiuNbEyRNwWwUrJtVKHDWGVsg6pNv07pimXgcgBbJSZCLgQyqYYtFGX8DQ==” 
            }  
        }, 
        “event”: “Transaction”, 
        “timestamp”:  1553872432  
    }


Create transactions

With these scripts and tools you can create a transaction JSON body, which you need to send in the API request create a transaction for approval.


Create a private and public key pair

To ensure security and trust in transactions and data that you want to be authorized by end-users, all transactions will need to be digitally signed prior to posting to the Multi-Factor Authentication API. You will need to create a private and public key pair using Curve25519.

Note: Private keys are only known to the owner and should never be shared. They should always be stored securely with a least-privilege access policy.

The public key created needs to be uploaded to COVR using the POST /api​/publickey request. See: Upload the public key.

You can create the key pair with the COVR Security Key Tool for Windows.

Note: The COVR Security Key Tool also assists in creating signatures for sending transactions. See: Create a signature.


Create a signature

All transactions sent to the API must include a signature in the JSON request payload.

Once you have created the data to be signed, it will be used with your private key to create a signature for the transaction. The cryptographic algorithm used to create the signature is ED25519.

To create a signature you can either use the COVR Security Key Tool for Windows or scripts.

Examples:


Create a transaction with COVR Security Key Tool

  1. Start the COVR Security Key Tool.
  2. Fill in the fields or click Auto Fill, make sure your public key is uploaded to the Covr servers. Alternatively past in your key pair.
  3. Click Sign Transaction.
  4. Click Copy JSON and paste it in the body of the API request.


You have to specify the following parameters:

Field Type Description
CompanyID String(GUID) This is the ID of your company that is created during account creation. This ID cannot be changed and you will need to use this ID when sending transactions to the API.
Company Client ID String(GUID) The ID of the client that you wish the transaction to be sent to. This identifier is posted to the webhook URL with eventType : Connection.
Action/Transaction ID string This is the ID of the transaction template.
ValidFrom (UNIX TimeStamp) UNIX/EPOCH Time Time that the transaction is valid from expressed in EPOCH/Unix-time.
ValidTo (UNIX TimeStamp) UNIX/EPOCH Time Time that validity the transaction ends. If a transaction is approved or rejected out of the time window between ValidFrom and ValidTo, this transaction will not be processed.
Subject/Title string In the transaction sent to end-users, Title appears on the mobile phone screen next to the logo.
Message string This is the transaction message you are requesting of end-users to accept or decline.
Accept Button Text string Caption of the button on the mobile phone screen that end-users will press to accept a transaction.
Reject Button Text string Caption of the button on the mobile phone screen that end-users will press to decline a transaction.
Create transaction API - JSON Request Body string The JSON body of the API request POST ​/api​/createTransaction


^^JSON request body example^^

{
    "CompanyClientId": "37d82b6d-8e7a-437b-bd1f-c0d2b2b56e75",
    "TemplateId": "a7fd401d-5310-4c2f-82cd-6c21cb077d65",
    "ValidFrom": 1553698960,
    "ValidTo": 1662681600,
    "Request": {
        "Title": "Pending transaction",
        "Message": "Are you sure you want to transfer €500 to John Doe?",
        "Accept": "Accept",
        "Reject": "Decline"
    },
    "Signature": "TestSignatureCnRnIPHO4xebg5oIj3zMmDmwM7UWXCIH/ktiwVn4I7cSCURQy6u25Rp/yKgv8L+vOR64w83FExXBQ=="
}


Create transaction in C

^^Signature creation script example in C#^^

    //Input Variables for CreateTransaction 
    var yourCompanyId = “88d82b6d-8e7a-437b-bd1f-c0d2b2b56e88”; 
    var companyClientId = “33d82b3d-3e7a-337b-bd1f-c0d2b2b56e33”; 
    var templateId = “a7fd401d-5310-4c2f-82cd-6c21cb077d65”; 
    var message = “Are you sure you want to transfer €500 to John Doe?”; 
    var title = “Pending transaction”; 
    var accept = “Accept”; 
    var reject = “Decline”; 
    var validFrom = DateTimeOffset.UtcNow.ToUnixTimeSeconds(); 
    var validTo = DateTimeOffset.UtcNow.AddMinutes(5).ToUnixTimeSeconds(); 


    public CreateTransaction CreateTransaction(string companyId, string companyClientId, string templateId,string message, string title, string accept, string reject, long validFrom, long validTo)
        {
            var signatureText =€"{companyId}{companyClientId}{templateId}{validFrom}{validTo}{title}{message}{accept}{reject}";
            var dataBytes = Encoding.UTF8.GetBytes(signatureText);
            var signature =CreateSignature(dataBytes);
            var transaction = new CreateTransaction
            {
                CompanyClientId = companyClientId,
                TemplateId = templateId,
                ValidFrom = validFrom,
                ValidTo = validTo,
                Request = new Request
                {
                    Title = title,
                    Message = message,
                    Accept = accept,
                    Reject = reject
                },
                Signature = signature
            };

            return transaction;
        }

        public string CreateSignature(byte[] dataBytes)
        {
            //Deserialize your Private Key
            var deserializedPrivateKey = Key.Import(SignatureAlgorithm.Ed25519,
                Convert.FromBase64String(_privateIdentityCompanyKey), KeyBlobFormat.RawPrivateKey);

            //Use ED25519 curve to sign the text with your private key 
            var signature = Convert.ToBase64String(SignatureAlgorithm.Ed25519.Sign(deserializedPrivateKey, dataBytes));

            return signature;
        }


Create transaction in Python

^^Requirements: pynacl==1.3.0^^

from nacl.signing import SigningKey
from nacl.encoding import Base64Encoder
from datetime import datetime, timedelta

class Request:
    def __init__(
        self,
        title: str,
        message: str,
        accept: str,
        reject: str
    ):
        self.title = title
        self.message = message
        self.accept = accept
        self.reject = reject

class Transaction:
    def __init__(
        self,
        company_id: str,
        company_client_id: str,
        template_id: str,
        message: str,
        title: str,
        accept: str,
        reject: str,
        valid_from: int,
        valid_to: int
    ):
        self.company_id = company_id
        self.company_client_id = company_client_id
        self.template_id = template_id,
        self.title = title
        self.message = message
        self.accept = accept
        self.reject = reject
        self.valid_from = valid_from
        self.valid_to = valid_to
        self.request = Request(title, message, accept, reject)
        self.key = SigningKey.generate()
        self.signature = self.__create_signature()

    def get_verify_key(self):
        """
        Return verify (public) key.
        """
        return self.key.verify_key.encode(encoder=Base64Encoder)

    def __create_signature(self):
        """
        Create signed message
        """
        message = f"{self.company_id}{self.company_client_id}{self.template_id}{self.valid_from}{self.valid_to}{self.title}{self.message}{self.accept}{self.reject}"
        data_bytes = message.encode('utf-8')
        signed_message = self.key.sign(data_bytes)
        return signed_message

if __name__ == "__main__":
    company_id: str = "88d82b6d-8e7a-437b-bd1f-c0d2b2b56e88"
    company_client_id: str = "33d82b3d-3e7a-337b-bd1f-c0d2b2b56e33"
    template_id: str = "a7fd401d-5310-4c2f-82cd-6c21cb077d65"
    message: str = "Are you sure you want to transfer €500 to John Doe?"
    title: str = "Pending transaction"
    accept: str = "Accept"
    reject: str = "Decline"
    valid_from = datetime.now()
    delta = timedelta(seconds=300)
    valid_to = valid_from + delta
    transaction = Transaction(
        company_id,
        company_client_id,
        template_id,
        message,
        title,
        accept,
        reject,
        int(datetime.timestamp(valid_from)),
        int(datetime.timestamp(valid_to)),
    )
    print(f"Verify key: {transaction.get_verify_key()}")
    print(f"Signed message: {transaction.signature}")


Create transaction in Node.js

^^nodeCreateTransaction.js^^
const { StringDecoder } = require('string_decoder');
const _sodium = require('libsodium-wrappers');

async function CreateTransaction(companyId, companyClientId, templateId, message, title, accept, reject, validFrom, validTo) {

    const signatureText = `${companyId}${companyClientId}${templateId}${validFrom}${validTo}${title}${message}${accept}${reject}`;

    const decoder = new StringDecoder('utf8'); 
    const data = decoder.write(signatureText);
    const dataBytes = Buffer.from(data);

    let signature = await CreateSignature(dataBytes);

    let transaction = {
        CompanyClientId: companyClientId,
        TemplateId: templateId,
        ValidFrom: validFrom,
        ValidTo: validTo,
        Request : {
            Title: title,
            Message: message,
            Accept: accept,
            Reject: reject
        },
        Signature: signature
    };

    console.log("transaction ", transaction);
    return transaction;
}

async function CreateSignature(dataBytes) {
    await _sodium.ready;
    const sodium = _sodium;


    let signKey = sodium.crypto_box_keypair("hex"); //publickKey/privateKey generation
    let sK = `${signKey.privateKey}`;
    console.log("private key ", sK);
    console.log("private key length ", sK.length);

    let sign = sodium.crypto_sign(dataBytes, sK); //signature generation using ed25519 algorithm and privateKey
    const signature = sodium.to_base64(sign, 1); 

    console.log("signature ", signature);
    return signature;
}

//Create variables for the transaction
let yourCompanyId = `88d82b6d-8e7a-437b-bd1f-c0d2b2b56e88`;
let companyClientId = `33d82b3d-3e7a-337b-bd1f-c0d2b2b56e33`;
let templateId = `a7fd401d-5310-4c2f-82cd-6c21cb077d65`;
let message = `Are you sure you want to transfer €500 to John Doe?`;
let title = `Pending transaction`;
let accept = `Accept`;
let reject = `Decline`;
let validFrom = new Date().getSeconds();  
let validTo = new Date().setMinutes(validFrom+300); 

CreateTransaction(yourCompanyId, companyClientId, templateId, message, title, accept, reject, validFrom, validTo);

^^package-lock.json^^
{
  "requires": true,
  "lockfileVersion": 1,
  "dependencies": {
    "libsodium": {
      "version": "0.7.6",
      "resolved": "https://registry.npmjs.org/libsodium/-/libsodium-0.7.6.tgz",
      "integrity": "sha512-hPb/04sEuLcTRdWDtd+xH3RXBihpmbPCsKW/Jtf4PsvdyKh+D6z2D2gvp/5BfoxseP+0FCOg66kE+0oGUE/loQ=="
    },
    "libsodium-wrappers": {
      "version": "0.7.6",
      "resolved": "https://registry.npmjs.org/libsodium-wrappers/-/libsodium-wrappers-0.7.6.tgz",
      "integrity": "sha512-OUO2CWW5bHdLr6hkKLHIKI4raEkZrf3QHkhXsJ1yCh6MZ3JDA7jFD3kCATNquuGSG6MjjPHQIQms0y0gBDzjQg==",
      "requires": {
        "libsodium": "0.7.6"
      }
    }
  }
}



How to...


Upload the public key

Public keys are used to verify the signature on transactions prior to sending any data to the recipient. We do this to create trust and validity of the transaction. Requests to the transaction API endpoint without a valid signature from the issuing company will not be processed.

You will need to create a private and public key pair. See: Create a private and public key pair.

POST /api​/publickey

^^Request example^^

{
  "publicKey": "123456MQYMwTYlhFhLgizu/1rSblA9siQBMhD1DdBs4=",
  "name": "Company A",
  "description": "Public key of company A"
}



Field Type Description
publicKey string This is the Company public key that you created, for example with the COVR Security Key Tool.
name string For example, the name of the company.
description string For example, what the key is used for.


The expected response is a 200 OK.

^^Response example^^
{
  "isSuccess": true,
  "errorCollector": []
}


Retrieve the access token for QR-code SDK

You need to retrieve an access token for the QR-code in the JavaScript SDK. No parameters required.

GET ​/api​/tokenForQRcode


The expected response is a 200 OK with the access token in the response body.

^^Response example^^
{
  "accessToken": "string"
}


Retrieve the company ID

Retrieves the company ID. No parameters needed.

GET ​/api​/companyId


The expected response is a 200 OK with the companyId in the response body.

^^Response example^^

{
  "companyId": "720b17ca-b32f-4f07-81ea-d5ed564d5b0c"
}


Create a transaction for approval

Transaction requests are sent to end-users. Sending a transaction to the API using an HTTPS POST request, requires that the transaction details are signed with your private key and that a signature is attached to the transaction payload.

COVR verifies the signature against your public key to ensure authenticity before sending the transaction to the end-user.

Transactions sent to the API with invalid signatures or no signature at all, will be rejected.

Note: The CompanyClientID is the ID of the client that you wish the transaction to be sent to. This identifier was posted to the webhook URL with eventType : Connection when an end-user scanned the QR-code.

POST ​/api​/createTransaction

^^Request example^^

    { 
    “companyClientId”: “37d82b6d-8e7a-437b-bd1f-c0d2b2b56e75”, 
    “templateId”: “a7fd401d-5310-4c2f-82cd-6c21cb077d65”, 
    “validFrom”:  1553698960, 
    “validTo”:  1553699260, 
    “request”:  { 
        “title”: “Pending transaction”, 
        “message”: “Are you sure you want to transfer €500 to John Doe?”,
        “accept”: “Accept”, 
        “reject”: “Decline” 
        }, 
        “signature”: “NzY4ZDhhMWItOWNjZC00ZDUxLTk1MjgtZTY5YmJlZTRhYzlj==” 
    }

Field Type Description
companyClientId string(GUID) The companyClientId is the ID of the client that you wish the transaction to be sent to. This identifier was posted to the webhook URL with eventType : Connection when an end-user scanned the QR-code. Save the CovrClientId in the data posted back to you and reference that CovrClientId as the companyClientId when posting transactions for that end-user.
templateId string This is the ActionId of the action (transaction) template.
validFrom UNIX/EPOCH time Time that the transaction is valid from expressed in EPOCH/Unix-time.
validTo UNIX/EPOCH time Time that the validation of the transaction ends. If a transaction is approved or rejected out of the time window between ValidFrom and ValidTo, this transaction will not be processed.
title string In the transaction sent to end-users Title appears on the mobile phone screen next to the logo.
message string This is the transaction message you are requesting of end-users to accept or decline.
accept string Caption of the button on the mobile phone screen that end-users will press to accept a transaction.
reject string Caption of the button on the mobile phone screen that end-users will press to decline a transaction.
signature string The signature you created with scripts or the COVR Security Key Tool.


^^Response example^^

    { 
    “CreatedAt”:1528109512, 
    “TransactionId”:”9DDEE058-4333-488F-A9BA-FA6AA78A33CE”, 
    “Status”:”Active” 
    }


Field Type Description
CreatedAt int Timestamp of the transaction.
TransactionId string This is the ID of the transaction. When the end-user has responded to the request, an HTTP POST is sent to the specified webhook URL.
Status string Status of the transaction.


Set user status

This endpoint is used to flag a user as inactive associated to your company.

POST ​/api​/setActiveStatus

^^Response example^^
{
  "userCompanyId": "string",
  "active": true
}


The expected response is a 200 Ok with Successful : true in the response body.


Retrieve actions

Returns a list of all the actions associated with your company account. The action ID returned is used in the CreateTransction JSON input model for sending a transaction to a user for authorization for the API.

GET ​/api​/actions

No parameters needed.


The expected response is a 200 Ok and returns an array of actions with their id and name.


Add actions

Actions refer to the action you would like sent to an end-user for verification. Name your action in a way that describes the workflow that it will be used for.

  • You can create as many actions as you wish depending on the business workflow that you are protecting.
  • Creating an action allows you to attach specific actions to your business workflows.
  • All transactions sent to the API must include a signature in the JSON request payload.

POST ​/api​/actions

The request body format is multipart/form-data.


Field Type Description
name string This is the name of the action you are creating. It should describe the workflow that it will be used for. For example, LogInAction or AccountChangeConfirmation.
backgroundImage string The path and name of the background image for the action template.
transactionImage string The path and name of the transaction image for the action template.


The expected response is a 200 Ok.


^^Response example^^
{
  "id": "f8ec49ad-994b-41d7-957b-5c0298c69225",
  "name": "TestNew",
  "backgroundImage": "https://cdncovrsecurityio.blob.core.windows.net/images/408e5839-31e2-4677-9f62-98539acd3aa0/f6ba7b2a-1004-4fa4-ae1e-a977b8c7e06a.png",
  "transactionImage": "https://cdncovrsecurityio.blob.core.windows.net/images/408e5839-31e2-4677-9f62-98539acd3aa0/967a7199-7339-45db-8bdc-24eb223767a8.png",
  "isSuccess": true,
  "errorCollector": []
}


Edit Actions

You can change existing actions with this endpoint. Use it in the same way as in Add Actions.

PUT ​/api​/actions

Field Type Description
name string This is the name of the action you are editing. It should describe the workflow that it will be used for. For example: LogInAction or AccountChangeConfirmation.
backgroundImage string The path and name of the background image for the action template.
transactionImage string The path and name of the transaction image for the action template.
id string ID of the action.


The expected response is a 200 Ok.


^^Response example^^
{
  "id": "f8ec49ad-994b-41d7-957b-5c0298c69225",
  "name": "TestNew",
  "backgroundImage": "https://cdncovrsecurityio.blob.core.windows.net/images/408e5839-31e2-4677-9f62-98539acd3aa0/f6ba7b2a-1004-4fa4-ae1e-a977b8c7e06a.png",
  "transactionImage": "https://cdncovrsecurityio.blob.core.windows.net/images/408e5839-31e2-4677-9f62-98539acd3aa0/967a7199-7339-45db-8bdc-24eb223767a8.png",
  "isSuccess": true,
  "errorCollector": []
}


Return codes

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.

Mopinion feedback