MIRACL Trust Backend API

# POST api.mpin.io/verification

Creates a Verification URL that can be used to enrol any device.

# Endpoint Authentication

  • Basic - The client ID and secret are used as a username:password pair for the HTTP Basic authentication of the request.
Authorization: "Basic <base64(<YOUR_CLIENT_ID:YOUR_CLIENT_SECRET>)>"

# Parameters

Name Type Required Description
userId Body True The user ID for which an identity with the service will be created
deviceName Body False A human readable name of the device on which the identity will be created
expiration Body False The expiration of the verification URL that will be be generated
delivery Body True Constant, should always be “no”
# Authentication Session Parameters
Name Type Required Description
accessId Body False ID of the authentication session if there is one initiated
stage Body False The stage of the authentication
# OIDC Parameters
Name Type Required Description
clientId Body True
redirectURI Body False
scope Body False
state Body False
nonce Body False

# Request Example

curl \
  --request POST \
  --user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}" \
  --data '{
    "userId": "'"${USER_ID}"'",
    "deviceName": "'"${DEVICE_NAME}"'",
    "clientId": "'"${YOUR_CLIENT_ID}"'",
    "redirectURI": "'"${YOUR_REDIRECT_URI}"'",
    "expiration": '"${EXPIRATION}"',
    "scope": ["openid", "email"],
    "delivery": "no"
  }' \
  https://api.mpin.io/verification

# Response Example

{
  "verificationURL": "https://api.mpin.io/verification/confirmation?client_id=<YOUR_CLIENT_ID>&code=<CODE>&redirect_uri=<YOUR_REDIRECT_URI>&stage=auth&user_id=<USER_ID>"
}

# GET api.mpin.io/api/v1/projects/<YOUR_PROJECT_ID>/audit

Returns the audit log for a project.

# Endpoint Authentication

  • Basic - The client ID and secret are used as a username:password pair for the HTTP Basic authentication of the request.

# Parameters

Name Type Required Description
projectId Path True Project ID
applicationId Query False Application ID
fromDate Query False Start date of the period
toDate Query False End date of the period
userId Query False User ID by which to filter the result set
mpinId Query False MPin ID by which to filter the result set
deviceName Query False Device name by which to filter the result set
offset Query False List offset
limit Query False List response limit

# Request Example

curl \
  --user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}" \
  "https://api.mpin.io/api/v1/projects/${YOUR_PROJECT_ID}/audit?fromDate=2021-06-01T00:00:00Z&toDate=2021-07-01T00:00:00Z&userId=${USER_ID}&limit=10&offset=0"

# Response Example

{
  "total": 1,
  "list": [
    {
      "IPAddress": "87.227.194.151",
      "appID": "353f337f-ed78-4436-8f3c-5389ed83555c",
      "appName": "Test",
      "country": "UK",
      "createdAt": "2021-10-01T07:52:27.204579Z",
      "deviceName": "Chrome on Linux",
      "eventStatus": "authenticate_success",
      "eventType": "authentication",
      "mpinID": "c324f5e55e377de0343f37019ad5b77b8b01bdfee40014a54d76fd934e36a792",
      "userID": "test@example.com"
    }
  ]
}

# GET api.mpin.io/api/v1/projects/<YOUR_PROJECT_ID>/mpinids

Returns the list of MPin IDs for a project.

# Endpoint Authentication

  • Basic - The client ID and secret are used as a username:password pair for the HTTP Basic authentication of the request.

# Parameters

Name Type Required Description
projectId Path True Project ID
userId Query False User ID by which to filter the result set
deviceName Query False Device name by which to filter the result set
labels Query False Labels by which to filter the result set
revoked Query False Revocation status by which to filter the result set
offset Query False List offset
limit Query False List response limit

# Request Example

curl \
  --user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}" \
  "https://api.mpin.io/api/v1/projects/${YOUR_PROJECT_ID}/mpinids?userId=${USER_ID}&deviceName=${DEVICE_NAME}&labels=${LABELS}&revoked=false&limit=10&offset=0"

# Response Example

{
  "total": 1,
  "list": [
    {
      "mpinId": "c324f5e55e377de0343f37019ad5b77b8b01bdfee40014a54d76fd934e36a792",
      "projectId": "86cd3e64-f641-416a-bf80-64b9b7eef8ea",
      "userId": "test@example.com",
      "deviceName": "Chrome on Windows",
      "labels": ["<LABEL_A>", "<LABEL_B>"],
      "ip": "87.227.194.151",
      "country": "UK",
      "dvs": false,
      "createdAt": "2021-08-12T14:54:10.817054Z",
      "updatedAt": "2021-08-12T14:54:10.819274Z",
      "revoked": false
    }
  ]
}

# PUT api.mpin.io/api/v1/projects/<PROJECT_ID>/mpinids/{mpinId}

Updates a device registration.

# Endpoint Authentication

  • Basic - The client ID and secret are used as a username:password pair for the HTTP Basic authentication of the request.

# Parameters

Name Type Required Description
deviceName Body True A human-readable name for the device registration. It is used in the MIRACL Trust PIN Pad and can be used in a Customer-Hosted PIN Pad implementation.
labels Body False List of labels attached to the device. It can be used in a Customer-Hosted PIN Pad implementation.

# Request Example

curl \
  --request PUT \
  --user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}" \
  --data '{
    "deviceName":"'"${NEW_DEVICE_NAME}"'",
    "labels": ["'"${LABEL_A}"'", "'"${LABEL_B}"'"]}'
  }' \
  "https://api.mpin.io/api/v1/projects/${YOUR_PROJECT_ID}/mpinids/${MPIN_ID}"

# Response Example

{
  "mpinId": "c324f5e55e377de0343f37019ad5b77b8b01bdfee40014a54d76fd934e36a792",
  "userId": "test@example.com",
  "deviceName": "<NEW_DEVICE_NAME>",
  "labels": ["<LABEL_A>", "<LABEL_B>"],
  "ip": "87.227.194.151",
  "country": "UK",
  "dvs": false,
  "createdAt": "2023-05-17T13:07:24.59692Z",
  "updatedAt": "2023-05-17T13:07:24.597557Z",
  "revoked": false
}

# POST api.mpin.io/api/v1/projects/<PROJECT_ID>/mpinids/{mpinId}/revocation

Revoke an identity.

# Endpoint Authentication

  • Basic - The client ID and secret are used as a username:password pair for the HTTP Basic authentication of the request.

# Parameters

Name Type Required Description
projectId Path True Project ID
mpinId Path True MPin ID to be revoked
reason Body False Reason for the revocation

# Request Example

curl \
  --request POST \
  --user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}" \
  --data '{
    "reason":"account expiration"
  }' \
  "https://api.mpin.io/api/v1/projects/${YOUR_PROJECT_ID}/mpinids/${MPIN_ID}/revocation"

# Response Example

{
  "hashMPinID": "<MPIN_ID>",
  "reason": "account expiration"
}

# POST api.mpin.io/dvs/verify

Verify a signature produced by the MIRACL DVS scheme.

# Endpoint Authentication

  • Basic - The client ID and secret are used as a username:password pair for the HTTP Basic authentication of the request.

# Parameters

Name Type Required Description
signature Body True Signature object
timestamp Body True Timestamp
type Body True Request type

# Request Example

curl \
  --request POST \
  --user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}" \
  --data '{
    "signature": {
      "hash": "74657374",
      "u": "041f98fb7ba291883881de0b806dec08b05586dd47c56b6c123e37dcf4fe29d888160b2f53582a78df34329e22867863b633d59d1c043719998651ad2b88060378",
      "v": "040120e4ed4054327e44f39f303ab1b6106d4a8b45986e8b17e3061a3a877628331a087da40ed5777163f60fd384bbbd2d41bb1188f10cd9f04ea47332f0fe89b4",
      "mpinId": "7b22696174223a313634393430343334372c22757365724944223a226976616e2e746f64696e6f76406d697261636c2e636f6d222c22634944223a2238366364336536342d663634312d343136612d626638302d363462396237656566386561222c2273616c74223a22686c566a4b6c4851326b534b304a6542716244305867222c2276223a352c2273636f7065223a5b22647673225d2c22647461223a5b5d2c227674223a22647673227d",
      "publicKey": "17e94f0538c772fc1b6542ffc014d2593b91e65745c4c05333c3d860cbe3c0c2070ec55a66201e1c3962e5230f3334579aaff5f82d4b9c4f0a0c016c57943f32160c1bbc4abed6bffe473b9fe966cb9f49f07bcae1051b6df20079fb15975c8e0a6bd6e09c332a6b59c4f998469bd162522379b1bc1d2faab5c7527163179b3e",
      "dtas": "WyJjNWE0MjIyYTBhN2JiY2ZlNmVhNWI0MTRmMWIwMmFhNTUxN2VkZGFiZTU1ZDBhZDQ1YjZhOGFmMjUzMTk1Yzc1IiwiN2ZmYjFmODE1YWNkMGE4YjMxM2JkZDk1NjQ0MDExODRmNzZkZTgxYThkNDgxZjg5NzVlMDU4ZjM2YjU2MTZmYiJd"
    },
    "timestamp":1649401561,
    "type":"verification"
  }' \
  https://api.mpin.io/dvs/verify

# Response Example

{
  "certificate": "eyJhbGciOiJSUzI1NiIsImtpZCI6InMxIn0.eyJjQXQiOjE2NDk0MDQ1ODAsImV4cCI6MTY0OTQwNDU5MCwiaGFzaCI6Ijc0NjU3Mzc0In0.BoMXXJVdiJ3TNQ1m_qz2GMo9J9EniUHJz14XMmVOBJPBWjw6UWTn2G2henNOauB7t6oBqqtLhRudLr3KY1kLgWorOSXlvISoZicEFGsmUfEXS-hxP3d01acE0cRnqMmi1Au4VXbREdwLy7I7Cwb4ptLrziYvkEVh7KdbAMsD6Bw"
}

# GET api.mpin.io/dvs/jwks

Get the JSON Web Key Sets for the MIRACL Trust DVS service.

# Request Example

curl https://api.mpin.io/dvs/jwks

# Response Example

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "s1",
      "n": "kWp2zRA23Z3vTL4uoe8kTFptxBVFunIoP4t_8TDYJrOb7D1iZNDXVeEsYKp6ppmrTZDAgd-cNOTKLd4M39WJc5FN0maTAVKJc7NxklDeKc4dMe1BGvTZNG4MpWBo-taKULlYUu0ltYJuLzOjIrTHfarucrGoRWqM0sl3z2-fv9k",
      "e": "AQAB"
    }
  ]
}