MCS-1.9.1000.1 WebSocket API

Provides a request-response API for local WebSocket clients to interact with MyID components.

Table of Contents

 

Changelog

Pre-Requisites

To use this API, the following are required:

Some Applets require additional components be installed:

Workflow invocation requires the installation and configuration of additional MyID client(s), depending on your use-case:

 

API Notes

General Usage

Using Global Windows Service

When self-hosting the WebSocket server, MCS must bind to a port. Once an instance of MCS has bound to a port, no other instances of MCS can bind to that same port. This means that, by default, only a single instance of MCS can be running and hosting WebSockets at any one time on a single machine.

As of 1.8.1000.1, MCS can operate in a mode whereby the WebSocket server is not hosted by the MCS executable, but rather by a Windows Service that delegates incoming requests to pre-registered instances of MCS. This enables the use of MCS on multi-tenant editions of Windows, where multiple users on a single machine need to use MCS concurrently, by providing a single WebSocket server, with a single port-binding, shared between all instances of MCS. In this mode, callers provide a pre-registered SessionId in requests that allows the Windows Service to identify the instance of MCS that should be delegated to.

Note: Support for MCS with the global-service requires MyID 12.5 or higher, and cannot be used with previous versions of MyID.

 

 

 

 

 

Applets

MCS provides GUI applets to perform the following functions:

 

SelectCard

Presents the operator with a device-picker, and returns the details of the selected security device.

Select Card screenshot

There are two variants of SelectCard:

Note: Both variants of SelectCard return the same output.

Input (Unauthenticated/Context-Free)

Type Method
Applet SelectCard

Arguments

None

Example Input

{
  "Type": "Applet",
  "Method": "SelectCard"
}

Input (Authenticated/Contextual)

Requires MyID 12.6.0 or higher.

Type Method
Applet SelectCard

Arguments

Name Type Description Allowed values
Token string OAuth token providing context A valid authentication token. For more information on how to acquire a token, see the Obtaining an operation extension token section of the MyID documentation.

Example Input

{
  "Type": "Applet",
  "Method": "SelectCard",
  "Args": {
    "Token": "token"
  }
}

Output

Name Type Description Returned values
Success bool Success state true/false
SerialNumber string Device serial The device's serial number or null if no selection
DeviceTypeName string Device type The type of the device, or null if no selection
ChipType string Chip type The device's reported chip-type, or null if not reported or no selection.
DeviceVersion string Applet version The device's reported version, or null if not reported or no selection.

Example Output

{
    "Success": true,
    "SerialNumber": "OBERTHUR0123456789",
    "DeviceTypeName": "Oberthur ID-One PIV",
    "ChipType": "Oberthur ID-One PIV",
    "DeviceVersion": "02.34"
}

 


LoginWithCard

Presents the operator with a device-picker, then allows the operator to login to MyID with the selected device and return the session GUID.

Card login screenshot

Input

Type Method
Applet LoginWithCard

Example input

{
    "Type": "Applet",
    "Method": "LoginWithCard"
}

Arguments

None

Output

Name Type Description Returned values
Success bool Success state true/false
SessionGuid string The GUID associated with the logon session A session GUID if logon succeeded, else null

Example output

{
    "Success": true,
    "SessionGuid": "-7850638,6EDEA9BC-BBAB-4E6C-9850-6035CA300BD2"
}

 


CaptureFingerprints

Presents the operator with a fingerprint capture dialog containing a list of fingers to be captured, and immediately starts scanning for the first impression. The captured prints are returned to the caller in INCITS-378 format as part of a JSON block that includes additional metadata and is formatted for the MyID Core API.

Note: as per the pre-requisites, this applet requires additional components corresponding to your fingerprint capture device-type be installed.

There are two different modes for the CaptureFingerprints API:

Specific-Finger Capture

Specific-finger capture screenshot

Unspecified Single-Finger Capture

Unspecified single-finger capture screenshot

Input

Type Method
Applet CaptureFingerprints

Arguments

Name Type Description Allowed values
FingersToCapture string Fingers to be captured Semi-colon delimited string of Finger IDs (case-insensitive) for specific-finger capture
OR
"ANY" (case-insensitive) for unspecified single-finger capture.
CaptureDeviceType string Fingerprint capture device-type One of the supported fingerprint capture device-types (case-insensitive).

Finger IDs

Value Description
LT Left thumb
LI Left index-finger
LM Left middle-finger
LR Left ring-finger
LL Left little-finger
RT Right thumb
RI Right index-finger
RM Right middle-finger
RR Right ring-finger
RL Right little-finger

Fingerprint Capture Device-Types

Value Description
Secugen Capture using a Secugen fingerprint reader
UareU Capture using a UareU fingerprint reader

Example specific-finger capture input

{
    "Type": "Applet",
    "Method": "CaptureFingerprints",
    "Args": 
    {
        "FingersToCapture": "RT;RI",
        "CaptureDeviceType": "Secugen"
    }
}

Example unspecified single-finger capture input

{
    "Type": "Applet",
    "Method": "CaptureFingerprints",
    "Args": 
    {
        "FingersToCapture": "ANY",
        "CaptureDeviceType": "Secugen"
    }
}

Output

Name Type Description Returned values
Success bool Success state true/false
fingers JSON Captured fingerprints INCITS 378 minutia in MyID Core API JSON format, or null if nothing captured

Example specific-finger capture output

{
  "Success": true,
  "fingers": {
    "rt": {
        "bioDeviceId": "{C4723C9E-828F-497F-AD2E-D15EFA17B971}",
        "minutia": {
          "format": "378",
          "data": "<INCITS 378 Data>"
        },
        "quality": "97",
        "status": "P"
    },
    "ri": {
        "bioDeviceId": "{C4723C9E-828F-497F-AD2E-D15EFA17B971}",
        "minutia": {
          "format": "378",
          "data": "<INCITS 378 Data>"
        },
        "quality": "96",
        "status": "P"
    }
  }
}

Example unspecified single-finger capture output

{
  "Success": true,
  "fingers": {
    "any": {
      "bioDeviceId": "{C4723C9E-828F-497F-AD2E-D15EFA17B971}",
      "minutia": {
          "format": "378",
          "data": "<INCITS 378 Data>"
      },
      "quality": "97",
      "status": "P"
    }
  }
}

 


CaptureFacialBioWithMic

Presents the user with the MyID Image Capture (MIC) tool, which utilises Aware PreFace to capture facial biometrics according to pre-defined compliance profiles. In addition to the INCITS-385 biometric data, MIC also provides the captured image as a standard JPEG for use in more conventional scenarios (e.g. displaying in a browser, or printing onto a smartcard).

Note: as per the pre-requisites, this applet requires that the separate Aware PreFace components be installed.

MyID Image Capture screenshot

Input

Type Method
Applet CaptureFacialBioWithMic

Arguments

Name Type Description Allowed values
MustConformToProfile bool Are non-compliant images allowed true/false
MaxOptimisationPasses int Maximum attempts to make image conform to profile >=1, 3 recommended
HairColour int Hair colour to be included in bio data INCITS-385-2004 hair colour
EyeColour int Eye colour to be included in bio data INCITS-385-2004 eye colour
Gender int Gender to be included in bio data INCITS-385-2004 gender
Profiles string Compliance profiles Aware PreFace profile XML in MyID JSON structure, encoded as Base64 string

Hair Colour

These values correspond to those in the ANSI INCITS 385-2004 standard.

Value Description
0 Unspecified
1 Bald
2 Black
3 Blonde
4 Brown
5 Gray
6 Red
16 Blue
19 Sandy
20 Auburn
21 White
22 Strawberry
32 Green
48 Orange
64 Pink
255 Unknown or Other

Eye Colour

These values correspond to those in the ANSI INCITS 385-2004 standard.

Value Description
0 Unspecified
1 Blue
2 Brown
3 Green
16 Multi-coloured
18 Hazel
32 Pink
34 Maroon
255 Unknown or Other

Gender

These values correspond to those in the ANSI INCITS 385-2004 standard.

Value Description
0 Unspecified
1 Male
2 Female
3 Unknown

Aware PreFace Profiles

MyID provides a default PIV Card Profile as part of installation, which can be found in <MyIDServerInstallPath>\rest.core\awareProfiles\core\AwareProfiles.json.

Example input

{
    "Type": "Applet",
    "Method": "CaptureFacialBioWithMic",
    "Args" :
    {
        "MustConformToProfile": true,
        "MaxOptimisationPasses": 3,
        "HairColour": 1,
        "EyeColour": 2,
        "Gender": 1,
        "Profiles": "Base64 Profile Data"
    }
}

Output

Name Type Description Returned values
Success bool Success state true/false
facial JSON Captured facial data INCITS 385 minutia and standard JPEG in MyID Core API JSON format
Error string An optional error-message Provided when process fails with an error, otherwise null.

Example output

{
   "Success": true,
   "facial": {
      "template": {
         "format": "385",
         "data": "<INCITS 385 Data>"
      },
      "photo": {
         "mimetype": "image/jpeg",
         "data": "<Base64 JPEG>"
      },
      "bioDeviceId": "{DF6544E8-5F02-45c6-A599-C24BE4BC5A69}",
      "profile": "FIPS PIV Card",
      "compliant": true
   },
   "Error": null
}	

 


ScanDocument

Presents the operator with MyID Document Scanner (MDS), which can be used to scan documents using scanners supporting either the TWAIN or WIA interfaces. Where a scanner can only perform a single-page scan, multiple scans can be performed to capture additional pages. Basic control of the scanner is provided through the MDS UI when using TWAIN, and, where supported, the manufacturer's driver UI can be invoked when scanning. When using WIA, the standard Windows UI is used for scanning.

Scanned documents are returned as a single JPEG; where multiple pages have been captured they are arranged in a grid and combined into a single image.

Note: as-per the pre-requisites, this applet requires the separate TWAIN component be installed to support scanners on the TWAIN interface. WIA can, where supported by the scanner, be used without additional components.

MyID Document Scanner screenshot

Input

Type Method
Applet ScanDocument

Arguments

None

Example input

{
  "Type": "Applet",
  "Method": "ScanDocument"
}

Output

Name Type Description Returned values
Success bool Success state true/false
Document string The captured document A base64-encoded JPEG of all captured pages, or null if nothing captured.

Example output

{
  "Success": true,
  "Document": "<Base64 JPEG>"
}	

 


ModifyImage

Presents the operator with the MyID Image Editor (MIE), which can be used to perform simple image editing. Primarily a cropping tool, MIE can also be used to adjust brightness, contrast, and rotation of a supplied image.

Note: Images are returned as JPEG regardless of their input type.