MCS-1.10.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 and Process-Requests 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.

Header

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

Header

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

Header

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

Header

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

Header

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.

MyID Image Editor screenshot

Input

Header

Type Method
Applet ModifyImage

Arguments

None

Name Type Description Allowed values
Base64Image string Input image Base64-encoded BMG, GIF, JPEG, or PNG
Rotation int Initial image rotation 0, 90, 180, 270
MaxHeight int Maximum height of output >=1 to restrict height of output, otherwise 0
MaxWidth int Maximum width of output >=1 to restrict width of output, otherwise 0
ValidateSize bool Whether to enforce MaxHeight and MaxWidth true/false
CropHeight int Fixed crop-height >=1 to set the height of the output, 0 otherwise
CropWidth int Fixed crop-width >=1 to set the width of the output, 0 otherwise
AspectRatio string Aspect ratio to enforce on cropped area X:Y where X and Y are horizontal and vertical dimensions respectively
JPEGCompressionRatio int The quality to use when rendering the JPEG 1-100, where 100 provides the highest quality result.

The following describes the behaviour when the different crop options are provided:

MaxHeight MaxWidth ValidateSize CropHeight CropWidth AspectRatio Result
✔️ or ❌ ✔️ or ❌ ✔️ or ❌ ✔️ ✔️ ✔️ or ❌ A fixed-size crop, as CropHeight & CropWidth are set and can't be reconciled with the other settings.
✔️ ✔️ ✔️ A free-selection crop whose output will have max height/width applied.
✔️ or ❌ ✔️ or ❌ A free-selection crop whose output can be any size.
✔️ ✔️ ✔️ ✔️ A fixed aspect-ratio crop whose output will have max height/width applied.
✔️ or ❌ ✔️ or ❌ ✔️ A fixed aspect-ratio crop whose output can be any size.

Example input

{
    "Type": "Applet",
    "Method": "ModifyImage",
    "Args" :
    {
        "Base64Image": "<Base64 Image>",
        "Rotation": 90,
        "MaxHeight": 600,
        "MaxWidth": 400,
        "ValidateSize": true,
        "CropHeight": 0,
        "CropWidth": 0,
        "AspectRatio": "2:3",
        "JPEGCompressionRatio": 1
    }
}

Output

Name Type Description Returned values
Success bool Success state true/false
Base64Image string Edited image Base64-encoded JPEG if an image was returned, null otherwise
Height int The height of the edited image >0 if an image was returned, 0 otherwise
Width int The width of the edited image >0 if an image was returned, 0 otherwise
MimeType string The mime-type of the edited image image/jpeg if an image was returned, null otherwise

Example output

{
   "Success": true,
   "Base64Image": "<Base64 Image>",
   "Height": 300,
   "Width": 200,
   "MimeType": "image/jpeg"
}	

 

Workflows

MCS allows a caller to invoke MyID workflows in external clients via the WebSocket API:

 

StartWithToken

Uses an OAuth token to initialise a workflow in an external client, returning the result on completion. Initial authentication to MyID is provided via the token, which also contains metadata about the workflow to be started.

Note: as-per the pre-requisites, this applet requires the separate MyID Desktop and/or the MyID Self-Service Application be installed.

MyID Desktop launched from StartWithToken:

MyID Desktop screenshot

MyID Self-Service Application launched from StartWithToken:

MyID Self-Service Application screenshot

Supported Operations

ID Name Supported Server Supported DSK Supported SSA
216 Collect My Card 12.3.0+ N/A 3.12.1000.1+
242 Collect My Updates 12.3.0+ N/A 3.12.1000.1+
270 Reprovision Card 12.3.0+ 3.12.1000.1+ N/A
296 Erase Card 12.3.0+ 3.12.1000.1+ N/A
297 Reset Card PIN 12.3.0+ 3.12.1000.1+ N/A
5000 Unlock Credential 12.3.0+ 3.12.1000.1+ N/A
5002 Collect Card 12.3.0+ 3.12.1000.1+ N/A
5007 Assisted Activation 12.3.0+ 3.12.1000.1+ N/A
102 Add Group 12.4.0+ 3.13.1000.1+ N/A
105 Amend Group 12.4.0+ 3.13.1000.1+ N/A
106 Remove Group 12.4.0+ 3.13.1000.1+ N/A
108 Edit Groups 12.4.0+ 3.13.1000.1+ N/A
110 Change My Security Phrases 12.4.0+ N/A 3.13.1000.1+
142 Manage My Additional Identities 12.4.0+ 3.13.1000.1+ N/A
221 Batch Request Card 12.4.0+ 3.13.1000.1+ N/A
245 Activate My Card 12.4.0+ N/A 3.13.1000.1+
252 Batch Encode Card 12.4.0+ 3.13.1000.1+ N/A
255 Reset My PIN 12.4.0+ N/A 3.13.1000.1+
269 Reprovision My Card 12.4.0+ 3.13.1000.1+ N/A
404 System Events 12.4.0+ 3.13.1000.1+ N/A
405 Audit Reporting 12.4.0+ 3.13.1000.1+ N/A
406 Bureau Requests 12.4.0+ 3.13.1000.1+ N/A
409 System Status 12.4.0+ 3.13.1000.1+ N/A
410 MI Reports 12.4.0+ 3.13.1000.1+ N/A
701 Issued Certificates 12.4.0+ 3.13.1000.1+ N/A
702 Certificate Requests 12.4.0+ 3.13.1000.1+ N/A
703 Revoked Certificates 12.4.0+ 3.13.1000.1+ N/A
705 Collect Certificates 12.4.0+ 3.13.1000.1+ N/A
706 Collect My Certificates 12.4.0+ 3.13.1000.1+ N/A
708 Validate Certificate Request 12.4.0+ 3.13.1000.1+ N/A
709 Recover Certificates 12.4.0+ 3.13.1000.1+ N/A
710 Recover My Certificates 12.4.0+ 3.13.1000.1+ N/A
723 Request Device Identity 12.4.0+ 3.13.1000.1+ N/A
726 Request Key Recovery 12.4.0+ 3.13.1000.1+ N/A
727 Approve Key Recovery 12.4.0+ 3.13.1000.1+ N/A
728 Collect Key Recovery 12.4.0+ 3.13.1000.1+ N/A
729 View Key Recovery 12.4.0+ 3.13.1000.1+ N/A
730 Collect My Key Recovery 12.4.0+ 3.13.1000.1+ N/A
731 Upload PFX File 12.4.0+ 3.13.1000.1+ N/A
806 Edit Roles 12.4.0+ 3.13.1000.1+ N/A
807 Credential Profiles 12.4.0+ 3.13.1000.1+ N/A
810 Card Layout Editor 12.4.0+ 3.13.1000.1+ N/A
811 Certificate Authorities 12.4.0+ 3.13.1000.1+ N/A
813 Security Settings 12.4.0+ 3.13.1000.1+ N/A
814 Audited Items 12.4.0+ 3.13.1000.1+ N/A
815 Job Management 12.4.0+ 3.13.1000.1+ N/A
816 Operation Settings 12.4.0+ 3.13.1000.1+ N/A
819 List Editor 12.4.0+ 3.13.1000.1+ N/A
820 Credential Stock 12.4.0+ 3.13.1000.1+ N/A
823 Licensing 12.4.0+ 3.13.1000.1+ N/A
831 Directory Management 12.4.0+ 3.13.1000.1+ N/A
832 Import Serial Numbers 12.4.0+ 3.13.1000.1+ N/A
834 Email Templates 12.4.0+ 3.13.1000.1+ N/A
836 Key Manager 12.4.0+ 3.13.1000.1+ N/A
837 External Systems 12.4.0+ 3.13.1000.1+ N/A
841 Add Devices 12.4.0+ 3.13.1000.1+ N/A
842 Edit Devices 12.4.0+ 3.13.1000.1+ N/A
843 Notifications Management 12.4.0+ 3.13.1000.1+ N/A
1001 Manage Applet 12.4.0+ 3.13.1000.1+ N/A
1002 Manage GlobalPlatform Keys 12.4.0+ 3.13.1000.1+ N/A
1302 Request My ID 12.4.0+ 3.13.1000.1+ N/A
1405 Cancel Device Identity 12.4.0+ 3.13.1000.1+ N/A
1413 Validate Device Request 12.4.0+ 3.13.1000.1+ N/A
1441 Confirm Cancel Device Request 12.4.0+ 3.13.1000.1+ N/A
5003 Batch Collect Card 12.4.0+ 3.13.1000.1+ N/A
5013 Update My Device 12.4.0+ N/A 3.13.1000.1+
5015 Change My PIN 12.4.0+ N/A 3.13.1000.1+

Input

Header

Type Method
Workflow StartWithToken

Arguments

Name Type Description Allowed values
Token string OAuth token to start workflow with 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.
ClientData string The client to be used to complete the workflow "DSK" OR "SSA" to use a specific client, or, optionally, where an operation is supported by both DSK and SSA, a comma-separated list indicating a preference-order for the client to use; for example "DSK,SSA" would cause MCS to first attempt the operation with DSK, and, if it isn't installed, to then attempt the operation with SSA. Case-insensitive.
OpId string The operation ID of the workflow to be invoked. See: Supported Operations. The operation ID corresponding to the token.

Example input (specific client; in this case, DSK)

{
  "Type": "Workflow",
  "Method": "StartWithToken",
  "Args" :
  {
    "Token": "token",
    "ClientData": "DSK",
    "OpId": "123"
  }
}

Example input (prefer DSK, but allow SSA if DSK is not available)

{
  "Type": "Workflow",
  "Method": "StartWithToken",
  "Args" :
  {
    "Token": "token",
    "ClientData": "DSK,SSA",
    "OpId": "123"
  }
}

Output

Name Type Description Returned values
Success bool Success state true/false
ErrorCode string Reason for success state Workflow result-code
ExtendedErrorCode string The external client error-code Any error-code returned by DSK/SSA when a workflow fails, otherwise null
Message string A translated error-message Any error-message returned by DSK/SSA when a workflow fails, otherwise null

Workflow result-codes

Value Description
Success The workflow completed successfully
Aborted The workflow was aborted
NotInstalled A valid DSK/SSA installation was not found
FailedToConnect Unable to connect to the DSK/SSA process
Busy The DSK/SSA process is already servicing a request
FailedWithError The workflow failed, and DSK/SSA returned an error. Details in ExtendedErrorCode and Message.
FailedWithoutError The workflow failed, but DSK/SSA did not return an error
FailedWithException The workflow failed due to a code-exception. Details in ExtendedErrorCode and Message.
InvalidClientData The ClientData argument could not be parsed

Example success output

{
   "Success": true,
   "ErrorCode": "Success",
   "ExtendedErrorCode": null,
   "Message": null
}	

Example failure output

{
   "Success": false,
   "ErrorCode": "FailedWithError",
   "ExtendedErrorCode": "123",
   "Message": "Example error-message"
}

 

Process-Request

A process-request allows a caller to instruct MCS to perform some part of a process (for example, generating a PKCS#10 request), usually silently but with minor GUI elements where required.

 

PrintHtmlDocument

Allows a caller to:

Select Printer Dialog

Input

Header

Type Method
ProcessRequest PrintHtmlDocument

Arguments

Name Type Description Allowed values
Document string The HTML document to print HTML encoded in Base64
UseDefaultPrinter bool Whether or not to silently print to the default printer true/false

Example input

{
  "Type": "ProcessRequest",
  "Method": "PrintHtmlDocument",
  "Args" :
  {
    "Document": "Base64-encoded HTML",
    "UseDefaultPrinter": true
  }
}

Output

Name Type Description Returned values
Success bool Success state true/false
ErrorCode string Reason for failure PrintHtmlDocument Error Code

PrintHtmlDocument Error-Codes

Value Description
PrinterUnavailable WebView2 reported the selected printer is unavailable.
UserCancelled The operator dismissed the printer-selection dialog without making a selection.
OtherError WebView2 reported an unknown error occurred during printing.
WebView2NotInstalled A supported version of the WebView2 runtime was not detected. See: Pre-Requisites.
WebViewInitialisationFailure WebView2 failed to initialise. More details may be found in the MCS log. This can sometimes be caused by a standard user elevating to admin ('Run as Administrator', runas, etc), which is not supported.

Example success output

{
   "Success": true,
}	

Example failure output

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

 


ProcessCertIssuanceManifest

Requires MyID 12.7.0 or higher.

Process one or more soft-certificate issuances in one of the following ways as-per an issuance-manifest:

Input

Header

Type Method
ProcessRequest ProcessCertIssuanceManifest

Arguments

Name Type Description Allowed values
Manifest string The issuance manifest MyID Core API JSON (requests/[id]/collectSoftCertificateDevice) encoded in Base64.

Note: while only a subset of the data in the MyID Core API JSON is consumed by MCS, the entire model can be provided as-is for simplicity.

Example input

{
  "Type": "ProcessRequest",
  "Method": "ProcessCertIssuanceManifest",
  "Args" :
  {
    "Manifest": "Base64-encoded issuance manifest"
  }
}

Certificate SaveMechanism

This determines the action MCS will take for each corresponding certificate, and can be found at $.credStores[x].certificates[y].saveMechanism.

Value Description
AUTOSAVE Save certificate(s) to the first available empty external drive.
FILE Save certificate(s) to a user-specified directory.
STORE Add certificate(s) to the user's personal certificate store.

Output

Name Type Description Returned values
Success bool Success state true/false
ErrorCode string Reason for failure ProcessCertIssuanceManifest Error Code

ProcessCertIssuanceManifest Error-Codes

Note: Generally, MCS provides more detailed information (e.g. stack traces for exceptions) in its log when returning an error code.

Value Description
AcceptPkcs7Error MyID Client Components (UMC) threw an exception in AcceptPkcs7Ex2.
AutoSaveNotAllowed Auto-save has been disabled in the MCS configuration file.
CertLoadError Failed to load an archived certificate.
CertStoreError Failed to add an archived certificate to the user store.
FailedToWrite An exception occurred during a file-write operation.
FileExtensionNotAllowed Request included a file-extension that is not explicitly permitted. Default allowed extensions are cer and pfx.
PersistCertsError Generic error for unhandled exceptions. Check the MCS log for more information and ensure your manifest is valid then try again.
UserCancelled The user dismissed a dialog without making a positive selection.

Example success output

{
   "Success": true,
}	

Example failure output

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

 


ProcessCertRequestManifest

Requires MyID 12.7.0 or higher.

Generate PKCS#10 requests as-per a request manifest, and returns the input manifest with the $.credStores[x].certificates[y].pkcs10 properties populated.

Input

Header

Type Method
ProcessRequest ProcessCertRequestManifest

Arguments

Name Type Description Allowed values
Manifest string The issuance manifest MyID Core API JSON (requests/[id]/provisionSoftCertificateDevice) encoded in Base64.

Example input

{
  "Type": "ProcessRequest",
  "Method": "ProcessCertRequestManifest",
  "Args" :
  {
    "Manifest": "Base64-encoded requested manifest"
  }
}

Output

Name Type Description Returned values
Success bool Success state true/false
Result string The updated issuance manifest MyID Core API JSON encoded in Base64 with $.credStores[x].certificates[y].pkcs10 properties populated. null on error.
ErrorCode string Reason for failure ProcessCertRequestManifest Error Code

ProcessCertRequestManifest Error-Codes

Note: Generally, MCS provides more detailed information (e.g. stack traces for exceptions) in its log when returning an error code.

Value Description
InvalidCertRequestManifest The request manifest was provided in an unexpected format and could not be parsed.
CreatePkcs10Error MyID Client Components (UMC) threw an exception in CreatePkcs10Ex.
 

Example success output

{
   "Success": true,
   "Result": "<issuance manifest with PKCS10 nodes populated, encoded in Base64>"
}	

Example failure output

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

Configuration

MCS allows a caller to set configuration options and get client information via its WebSocket API:

 

GetVersion

Used to retrieve the MCS product-version so clients can determine the API level.

Input

Header

Type Method
Configuration GetVersion

Arguments

None

Example input

{
  "Type": "Configuration",
  "Method": "GetVersion"
}

Output

Name Type Description Returned values
Success bool Success state true/false
Version string MCS version MCS version string, e.g. MCS-1.6.1000.1

Example output

{
   "Version": "MCS-1.6.1000.1",
   "Success": true
}	

 


 

GetClientId

Used to retrieve the configurable client identifier. This can be useful for things like auditing; for example, MyID includes this value in its audit records when clients perform logons, execute workflows, etc.

Input

Header

Type Method
Configuration GetClientId

Arguments

None

Example input

{
  "Type": "Configuration",
  "Method": "GetClientId"
}

Output

Name Type Description Returned values
Success bool Success state true/false
ClientId string The configured client-identifier The configured client-identifier.

By default, the full machine-name of the host is returned, but this can be overridden in either the configuration file or the Windows registry. For more information on configuring the client-identifier, consult the MyID Documentation.

The following matrix shows how MCS determines from where it should retrieve the value:

In registry? In configuration file? Returns value from
✔️ ✔️ or ❌ Registry
✔️ Configuration file
Machine-name

Example output

{
   "ClientId": "CLIENT01.example.com",
   "Success": true
}	

 


SetLanguage

Allows a caller to specify a language to be used. This will apply to GUI applets and external clients (e.g. MyID Desktop) when they are invoked by MCS. If the requested language is already in use then this call has no effect.

Note: This call causes MCS to request the translations for the specified language from the MyID server, but if the requested language is not installed then MyID will fall-back to the default language.

Note: Language changes will not immediately be reflected in any already-open GUIs, but rather the next time the GUI is opened; for example, if a device-picker is on-screen then the language it uses will not immediately change, but the next time it is opened it will reflect the new language.

Input

Header

Type Method
Configuration SetLanguage

Arguments

Name Type Description Allowed values
Language string The requested language IETF language tag, e.g. en-US, en-GB, etc (case-insensitive).

Example input

{
  "Type": "Configuration",
  "Method": "SetLanguage",
  "Args":
  {
    "Language": "en-GB"
  }
}

Output

Name Type Description Returned values
Success bool Success state true/false

Example output

{
   "Success": true
}	

SetTheme

Allows a caller to specify a theme to be used. This will apply to dialogs within MCS, along with any external applications (e.g. MyID Desktop) that MCS invokes. Note that this will temporarily override any local theme that has been applied. If the requested theme is already in use then this call has no effect.

Input

Header

Type Method
Configuration SetTheme

Arguments

Name Type Description Allowed values
theme string Theme to be applied Theme JSON, encoded as Base64 string
format string The format of the theme "palette"

Theme JSON

The theme JSON is derived directly from the JSON that MyID Operator Client uses for its theming, and can be copied directly from its configuration.

Theme JSON example

{
	"primary": {
	  "light": "rgba(76, 81, 111, 1)",
	  "main": "rgba(27, 29, 76, 1)",
	  "dark": "rgba(0, 0, 29, 1)",
	  "contrastText": "rgba(255, 255, 255, 1)",
	},
	"secondary": {
	  "light": "rgba(255, 202, 71, 1)",
	  "main": "rgba(255, 153, 0, 1)",
	  "dark": "rgba(198, 106, 0, 1)",
	  "contrastText": "rgba(255, 255, 255, 1)",
	},
	"error": {
	  "light": "rgba(229, 115, 115, 1)",
	  "main": "rgba(244, 67, 54, 1)",
	  "dark": "rgba(211, 47, 47, 1)",
	  "contrastText": "rgba(255, 255, 255, 1)",
	},
	"text": {
	  "primary": "rgba(0, 0, 0, 1)",
	  "secondary": "rgba(115, 115, 115, 1)",
	  "disabled": "rgba(0, 0, 125, 0.38)",
	  "hint": "rgba(255, 0, 0, 0.3)",
	},
	"common": {
	  "black": "rgba(0, 0, 0, 1)",
	  "white": "rgba(255, 255, 255, 1)",
	},
	"background": {
	  "paper": "rgba(255, 255, 255, 1)",
	  "default": "rgba(250, 250, 250, 1)",
	},
}

Note: While the following describes the entire JSON structure, only a subset of the values in the theme apply to MCS and external clients (e.g. MyID Desktop) at this time.

Name Model Description
primary Generic Colour Model Primary colour in the UI (buttons, text-boxes, etc).
secondary Generic Colour Model Secondary colour in the UI (some accents, highlights, etc).
error Generic Colour Model Not used.
text Text Colour Model Not used.
common Common Colour Model Not used.
background Background Colour Model Not used.

Generic Colour Model

Name Type Description
main RGBA String The main colour.
light RGBA String A light variant of the main colour.
dark RGBA String A dark variant of the main colour.
contrastText RGBA String A contrasting colour for when text is displayed over main/light/dark colour.

Text Colour Model

Name Type Description
primary RGBA String Primary text colour.
secondary RGBA String Secondary text colour.
hint RGBA String Hint-text colour.
disabled RGBA String Disabled-text colour.

Common Colour Model

Name Type Description
black RGBA String Black colour definition.
white RGBA String White colour definition.

Background Colour Model

Name Type Description
paper RGBA String An alternative background colour.
default RGBA String The default background colour.

RGBA String

A string representing the red, green, blue, and alpha channels of a colour in the format "rgba(R, G, B, A)"; for example, "rgba(27, 29, 76, 1)" is 'Intercede Blue'.

Name Type Description Range
R integer The Red colour intensity. 0 - 255
G integer The Green colour intensity. 0 - 255
B integer The Blue colour intensity. 0 - 255
A float The Alpha channel. 0 - 1

Example input, passing the default theme

{
	"Type": "Configuration",
	"Method": "SetTheme",
	"args": 
	{
		"theme": "ew0KCWNvbW1vbjogew0KCSAgYmxhY2s6ICdyZ2JhKDAsIDAsIDAsIDEpJywNCgkgIHdoaXRlOiAncmdiYSgyNTUsIDI1NSwgMjU1LCAxKScsDQoJfSwNCgliYWNrZ3JvdW5kOiB7DQoJICBwYXBlcjogJ3JnYmEoMjU1LCAyNTUsIDI1NSwgMSknLA0KCSAgZGVmYXVsdDogJ3JnYmEoMjUwLCAyNTAsIDI1MCwgMSknLA0KCX0sDQoJcHJpbWFyeTogew0KCSAgbGlnaHQ6ICdyZ2JhKDc2LCA4MSwgMTExLCAxKScsDQoJICBtYWluOiAncmdiYSgyNywgMjksIDc2LCAxKScsDQoJICBkYXJrOiAncmdiYSgwLCAwLCAyOSwgMSknLA0KCSAgY29udHJhc3RUZXh0OiAncmdiYSgyNTUsIDI1NSwgMjU1LCAxKScsDQoJfSwNCglzZWNvbmRhcnk6IHsNCgkgIGxpZ2h0OiAncmdiYSgyNTUsIDIwMiwgNzEsIDEpJywNCgkgIG1haW46ICdyZ2JhKDI1NSwgMTUzLCAwLCAxKScsDQoJICBkYXJrOiAncmdiYSgxOTgsIDEwNiwgMCwgMSknLA0KCSAgY29udHJhc3RUZXh0OiAncmdiYSgyNTUsIDI1NSwgMjU1LCAxKScsDQoJfSwNCgllcnJvcjogew0KCSAgbGlnaHQ6ICdyZ2JhKDIyOSwgMTE1LCAxMTUsIDEpJywNCgkgIG1haW46ICdyZ2JhKDI0NCwgNjcsIDU0LCAxKScsDQoJICBkYXJrOiAncmdiYSgyMTEsIDQ3LCA0NywgMSknLA0KCSAgY29udHJhc3RUZXh0OiAncmdiYSgyNTUsIDI1NSwgMjU1LCAxKScsDQoJfSwNCgl0ZXh0OiB7DQoJICBwcmltYXJ5OiAncmdiYSgwLCAwLCAwLCAxKScsDQoJICBzZWNvbmRhcnk6ICdyZ2JhKDExNSwgMTE1LCAxMTUsIDEpJywNCgkgIGRpc2FibGVkOiAncmdiYSgwLCAwLCAxMjUsIDAuMzgpJywNCgkgIGhpbnQ6ICdyZ2JhKDI1NSwgMCwgMCwgMC4zKScsDQoJfSwNCn0=",		
		"format": "palette",
	},
}

Output

Name Type Description Returned values
Success bool Success state true/false

Example output

{
   "Success": true
}	

© Intercede 2022, all rights reserved.