Provides a request-response API for local WebSocket clients to interact with MyID components.
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:
<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:
<add key="DskPath" value="C:\Program Files (x86)\Intercede\MyIDDesktop">
<add key="SsaPath" value="C:\Program Files (x86)\Intercede\MyIDApp\Self Service Application">
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
.
DisableAccessControl
is set to true
, MCS will accept API connections from any origin.MCS can only service a single request at a time
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.
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.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"
}
}
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.
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.
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.
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"
}
}
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"
}
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.
MCS provides GUI applets to perform the following functions:
Presents the operator with a device-picker, and returns the details of the selected security device.
There are two variants of SelectCard:
❕ Note: Both variants of SelectCard return the same output.
Type | Method |
---|---|
Applet | SelectCard |
None
Example Input
{
"Type": "Applet",
"Method": "SelectCard"
}
❗ Requires MyID 12.6.0 or higher.
Type | Method |
---|---|
Applet | SelectCard |
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"
}
}
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"
}
Presents the operator with a device-picker, then allows the operator to login to MyID with the selected device and return the session GUID.
Type | Method |
---|---|
Applet | LoginWithCard |
Example input
{
"Type": "Applet",
"Method": "LoginWithCard"
}
None
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"
}
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:
Type | Method |
---|---|
Applet | CaptureFingerprints |
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). |
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 |
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"
}
}
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"
}
}
}
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.
Type | Method |
---|---|
Applet | CaptureFacialBioWithMic |
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 |
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 |
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 |
These values correspond to those in the ANSI INCITS 385-2004 standard.
Value | Description |
---|---|
0 |
Unspecified |
1 |
Male |
2 |
Female |
3 |
Unknown |
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"
}
}
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
}
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.
Type | Method |
---|---|
Applet | ScanDocument |
None
Example input
{
"Type": "Applet",
"Method": "ScanDocument"
}
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>"
}
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.