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
• API Notes
  • General Usage
  • Using Global Windows Service
• Applets
  • SelectCard
  • LoginWithCard
  • CaptureFingerprints
  • CaptureFacialBioWithMic
  • ScanDocument
  • ModifyImage
• Workflows
  • StartWithToken
• Configuration
  • GetVersion
  • GetClientId
  • SetLanguage
  • SetTheme

Changelog

• 1.9.1000.1
  • Added support for authenticated/contextual card-selection in SelectCard.
• 1.8.1000.1
  • Added support for Using Global Windows Service.
• 1.7.1000.1
  • Added new GetClientId endpoint.
  • Added new SetTheme endpoint.
• 1.6.1000.1
  • First public release

Pre-Requisites

To use this API, the following are required:

• MyID Client Service 1.9.1000.1 (MCS-1.9.1000.1).
• MyID 12.3.0 or higher.
  • ⚠️ If you are using a version of MyID prior to 12.6.0 you will not be able to make full use of the new features in the MCS-1.9.1000.1 API. Make note of highlighted version-constraints in-line.
  • ✅ MCS-1.9.1000.1 provides backwards-compatibility with previous MCS APIs - consult the API documentation for the MCS version corresponding to your MyID release for the scope of the API available to you.

Some Applets require additional components be installed:

• CaptureFingerprints
  • The current integration patch corresponding to the fingerprint capture device-type to be used must be installed; for example, the Secugen patch must be installed to use a supported Secugen device. Consult the the MyID documentation for more details.
  • Without the corresponding patch, MCS will be unable to detect the fingerprint capture device.
• CaptureFacialBioWithMic
  • The current Aware PreFace patch must be installed. Consult the MyID Documentation for more details.
  • Without the PreFace patch, the MyID Image Capture window will display an error on launch.
• ScanDocument
  • To use scanners via the TWAIN interface, the current x86 TWAIN DSM patch must be installed. Consult the MyID Documentation for more details.
    • This is not required if you only intend to use scanners via the WIA interface.

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

• StartWithToken
  • StartWithToken can launch workflows with MyID Desktop (DSK) and/or MyID Self-Service Application (SSA).
    • For DSK workflows, DSK-3.12.1000.1 or higher is required.
    • For SSA workflows, SSP-3.12.1000.1 or higher is required.
    • For details on specific client/server support for particular operations, see: Supported Operations.
  • DSK/SSA must be configured to connect to the same MyID server as MCS.
  • If DSK/SSA is not installed in the default location, the path to the installation must be configured in the MCS configuration file. Within the <appSettings> node, add the following according to the client you are configuring, replacing the value (default path shown in examples) with the path to the client's installation directory:
    • MyID Desktop (DSK):

      <add key="DskPath" value="C:\Program Files (x86)\Intercede\MyIDDesktop">
      

    • MyID Self-Service Application (SSA):

      <add key="SsaPath" value="C:\Program Files (x86)\Intercede\MyIDApp\Self Service Application">
      

API Notes

General Usage

• With its default configuration, MCS hosts a local WebSocket server to provide the API. By default, this is available at ws://localhost:8081 - if you have configured MyID/MCS to use a different port, substitute 8081 for your configured port number.

  Basic WebSocket Example

  // Request to call GetVersion
  const request = 
  {
    Type: "Configuration", 
    Method: "GetVersion",
    ID: "Example"
  }
  
  // Connect to MCS
  const socket = new WebSocket("ws://localhost:8081");
  
  // Send message to MCS when WebSocket connects
  socket.onopen = function(e) 
  {
    socket.send(JSON.stringify(request));
  }
  
  // Handle response in `onmessage` event
  socket.onmessage = function(event) 
  {
    const response = JSON.parse(event.Data);
    if(response.ID == "Example")
    {
      // ID matches request; expected response.
      if(response.Success)  
      {
        alert(`MCS is version: {response.Version}`);
      } 
      else 
      {
        alert("GetVersion call failed");
      }
    } 
    else 
    {
      // ID doesn't match request; not the response we want.
    }
  }
  

• MCS only allows API connections from the local machine.

• MCS will, by default, reject API connections where the Origin header is unrecognised. To use the API, the origin of your caller must be added to the AccessControlAllowOrigin configuration or DisableAccessControl must be set to true.

  • ❗ Note: If DisableAccessControl is set to true, MCS will accept API connections from any origin.

• MCS can only service a single request at a time

  • If multiple requests are sent on the same WebSocket connection they are queued and executed in the order they were received.
  • If a request on a new WebSocket connection is made while a request is ongoing on another connection, it will immediately return a failure response.

• Requests are made by providing a 'header' containing a Type and Method to invoke, an optional ID, and an array of arguments (Args) where the method being called demands it.

  • When an ID is provided in the request header, MCS includes it in the response - this can make it simpler to pair API responses to their corresponding requests. MCS does not perform any 'uniqueness' checks on IDs, simply echoing the provided value in the response.
  • ❗ Note: Arguments are positional and must be presented in the documented order.

  Example request without arguments or ID. The response will not include an ID.

  {
      "Type": "SomeType",
      "Method": "SomeMethod"
  }
  

  Example request with ID, and without arguments. "SomeIdValue" will be the ID of the response.

  {
      "Type": "SomeType",
      "ID": "SomeIdValue",
      "Method": "SomeMethod"
  }
  

  Example request with arguments, and without ID. The response will not include an ID.

  {
      "Type": "SomeType",
      "Method": "SomeMethod",
      "Args": 
      {
          "SomeArg": "SomeArgValue",
          "SomeOtherArg": "SomeOtherArgValue"
      }
  }
  

  Example request with arguments and ID. "SomeIdValue" will be the ID of the response.

  {
      "Type": "SomeType",
      "Method": "SomeMethod",
      "ID": "SomeIdValue",
      "Args": 
      {
          "SomeArg": "SomeArgValue",
          "SomeOtherArg": "SomeOtherArgValue"
      }
  }
  

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.

• Configuring Global-Service Mode

  MCS must be configured to use the to use the global-service for WebSocket comms; to do this, add the following to the MCS configuration file:

  <add key="UseGlobalService" value="true"/>
  

  To validate that MCS can communicate with the global-service, you can launch MCS from the command-line with a test SessionID as follows:

  MyIDClientService.exe /sessionid:test
  

  Once available, select 'Show' from the MCS system-tray menu to see the debug log; if MCS successfully registered the ID with the global-service you will see the following in the log:

  Debug: Connecting to registration service...
  Debug: Connected: True
  Debug: Registering ID=test...
  Debug: Registration of test success: True
  

  If registration fails, ensure that the global-service is installed and running and retry.

• Registering a SessionId

  A SessionId must be pre-registered with the service before it can be used. To do this, a caller can provide a new ID with the myidmcs protocol; for example:

  myidmcs:///sessionid:exampleid
  

  ❗ Note: The initial install configures MCS as the myidmcs protocol-handler, but this can be subsequently reconfigured or blocked (e.g. with Group Policy). If the myidmcs protocol is not working as expected, verify that MCS is registered as the myidmcs protocol-handler, and that protocol-handling is not blocked.

  Alternatively, where a caller can launch the MCS executable directly, a SessionId can be provided as a command-line argument; for example:

  MyIDClientService.exe /sessionid:exampleid
  

  This causes an MCS instance within the same user-session as the browser to register the SessionId exampleid with the global-service. If there is an instance of MCS already running in the user-session, it will be re-used (i.e. one instance can be registered for many SessionIds). Following this registration, any incoming requests received by the global-service with the exampleid SessionId will be handled by the registered instance of MCS.

  ❗ Note: SessionId should be a unique value to avoid collisions between sessions. While MCS will accept any value for SessionId, Intercede recommends the use of a UUID. Responsibility for uniqueness rests with the caller, as MCS cannot validate the caller's intent when a SessionId is provided in a request.

• Including SessionId in Requests

  There are two additional properties that should be provided in request-headers:

  Name	Type	Description	Allowed Values
  SessionId	string	A value that identifies an instance of MCS.	Any
  SessionConfirmed	bool	Indicates whether the SessionId has been used successfully in a previous request.	true/false

  SessionConfirmed affects the period of time the global-service will wait for a response from a client before returning an error. The first time you use a SessionId, it may be the case that the instance of MCS is not yet available (e.g. still starting-up) - in this scenario, providing a SessionConfirmed value of false indicates to the global-service that it should wait for the client to become available (by default, this is up to 60 seconds), only returning an error if no client is found after the configurable timeout period. Conversely, if a SessionConfirmed value of true is provided, the global-service expects that the client is available and returns an error if it isn't in a much shorter time (by default, up to 5 seconds and usually immediately).

  ❗ Note: These properties are ignored when provided to MCS in standalone-mode, and so there is no need for the caller to determine the operating mode - they can be supplied in either mode without risk.

   

  Example request without arguments or ID, and a confirmed SessionId.

  {
      "Type": "SomeType",
      "Method": "SomeMethod",
      "SessionId": "exampleid",
      "SessionConfirmed": true
  }
  

  Example request without arguments or ID, and an unconfirmed SessionId.

  {
      "Type": "SomeType",
      "Method": "SomeMethod",
      "SessionId": "exampleid",
      "SessionConfirmed": false
  }
  

  Example request with ID, without arguments, and a confirmed SessionId.

  {
      "Type": "SomeType",
      "ID": "SomeIdValue",
      "Method": "SomeMethod",
      "SessionId": "exampleid",
      "SessionConfirmed": true
  }
  

  Example request with ID, without arguments, and an unconfirmed SessionId.

  {
      "Type": "SomeType",
      "ID": "SomeIdValue",
      "Method": "SomeMethod",
      "SessionId": "exampleid",
      "SessionConfirmed": false
  }
  

  Example request with arguments, without ID, and a confirmed SessionId.

  {
      "Type": "SomeType",
      "Method": "SomeMethod",
      "SessionId": "exampleid",
      "SessionConfirmed": true,
      "Args": 
      {
          "SomeArg": "SomeArgValue",
          "SomeOtherArg": "SomeOtherArgValue"
      }
  }
  

  Example request with arguments, without ID, and an unconfirmed SessionId.

  {
      "Type": "SomeType",
      "Method": "SomeMethod",
      "SessionId": "exampleid",
      "SessionConfirmed": false,
      "Args": 
      {
          "SomeArg": "SomeArgValue",
          "SomeOtherArg": "SomeOtherArgValue"
      }
  }
  

  Example request with arguments, ID, and a confirmed SessionId.

  {
      "Type": "SomeType",
      "Method": "SomeMethod",
      "ID": "SomeIdValue",
      "SessionId": "exampleid",
      "SessionConfirmed": true,
      "Args": 
      {
          "SomeArg": "SomeArgValue",
          "SomeOtherArg": "SomeOtherArgValue"
      }
  }
  

  Example request with arguments, ID, and an unconfirmed SessionId.

  {
      "Type": "SomeType",
      "Method": "SomeMethod",
      "ID": "SomeIdValue",
      "SessionId": "exampleid",
      "SessionConfirmed": false,
      "Args": 
      {
          "SomeArg": "SomeArgValue",
          "SomeOtherArg": "SomeOtherArgValue"
      }
  }
  

• Service-Level Errors

  There are a handful of additional error-codes that can be returned when communicating with MCS via the global-service:

  Error Code	Description	Solution
  InvalidSessionId	SessionId has not been registered, registration has not yet completed, or the MCS instance associated with a previously valid ID is no longer running.	Register a new SessionId and retry.
  InvalidRequestData	The data supplied in the request could not be processed. This usually indicates a development error that needs correcting.	Ensure the data provided is valid.
  UnresponsiveSessionClient	A client is registered against the provided SessionId and is running, but is not responding to requests.	Close the corresponding MCS instance, register a new SessionId, and retry. If the issue persists, increase the ClientConnectionTimeoutSeconds value in the global-service's appSettings file, restart the service, and try again.

  Errors at this level are returned in the following format:

  {
    "Success": false,
    "ErrorCode": "InvalidSessionId"
  }
  

• Mixed-Mode Environments

  In some scenarios, you may wish to use MCS with the global-service on some machines and in standalone mode on others. The main consideration for this is that the port configured for standalone MCS clients should be the same as the port configured for the global-service clients, as MyID expects to be able to communicate with MCS on a single specific port regardless of its operating mode.

  ❗ Note: While you can have MCS running in different modes on different machines, you cannot have MCS running in two different modes concurrently on the same machine; if you install and run the global-service on a machine that will be running MCS in standalone mode, and the ports are configured identically, MCS will fail to launch as it will not be able to bind to the port since it is already bound by the global-service.

Applets

MCS provides GUI applets to perform the following functions:

• Select a security device (SelectCard)
• Login to MyID with a security device (LoginWithCard)
• Capture fingerprints (CaptureFingerprints)
• Capture facial biometrics (CaptureFacialBioWithMic)
• Scan a document (ScanDocument)
• Crop an image and adjust its brightness/contrast (ModifyImage)

SelectCard

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

There are two variants of SelectCard:

• Unauthenticated/Context-Free
  • Without authentication, and depending on your MyID configuration, SelectCard may not show additional card information (e.g. card-holder name/image).
  • Without context, SelectCard will allow any card to be selected in the card-picker.
• Authenticated/Contextual
  • ❗ Requires MyID 12.6.0 or higher.
  • With authentication, SelectCard will be able to show additional card information (e.g. card-holder name/image) should the scope of the authentication allow it.
  • With context, SelectCard can prevent the operator from selecting cards that are inappropriate for the current operation.
  • Where the context provided to the applet is invalid, SelectCard will revert to the Unauthenticated/Context-Free behaviour.

❕ Note: Both variants of SelectCard return the same output.

Input (Unauthenticated/Context-Free)

Header

Arguments

None

Example Input

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

Input (Authenticated/Contextual)

❗ Requires MyID 12.6.0 or higher.

Header

Arguments

Example Input

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

Output

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.

Input

Header

Example input

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

Arguments

None

Output

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

• Allows >=1 fingers to be specified for capture.
• MyID uses this mode to perform enrolments, where captures are to be added to the MyID records.

Unspecified Single-Finger Capture

• A single, unspecified finger is captured without restriction.
• MyID uses this mode for verification, where the captured print is compared against the prints MyID has on record.

Input

Header

Arguments

Finger IDs

Fingerprint Capture Device-Types

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

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.

Input

Header

Arguments

Hair Colour

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

Eye Colour

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

Gender

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

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

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.

Input

Header

Arguments

None

Example input

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

Output

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.