# POST api.mpin.io/activate/initiate
Creates an MPin Identity and receives an activation token used to activate the identity during the registration process.
# 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 |
# Request Example
curl \
--request POST \
--user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}"
--data '{
"userId":"'"${USER_ID}"'",
"deviceName":"'"${DEVICE_NAME}"'"
}' \
https://api.mpin.io/activate/initiate
# Response Example
{
"hashMPinId": "ce1eb5b2da42cd5ba0c5f46365e7df0afe44cd1ccf26d880749144cdaa444c6c",
"actToken": "763c1005ca540c4db8e6811222c207ea",
"expireTime": 1634890606,
"redirectURI": ""
}
# POST api.mpin.io/verification
This is a beta API and can be a subject of change!
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 |
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}&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",
"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}
Changes the name of the registered device.
# 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 of the new device name |
# Request Example
curl \
--request PUT \
--user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}" \
--data '{
"deviceName":"'"${NEW_DEVICE_NAME}"'"
}' \
"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>",
"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"
}
]
}
# POST api.mpin.io/otp
Returns the generated OTP for that user ID.
# 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 | User ID |
deviceName | Body | True | Device Name |
# Request Example
export EXPIRES=$(date -d "+1 hour" -u +"%Y-%m-%dT%H:%M:%SZ")
export SIGNATURE=$(echo -n "${YOUR_CLIENT_ID}${USER_ID}${EXPIRES}" | openssl dgst -sha256 -hmac ${YOUR_CLIENT_SECRET} | grep -Po '(?<=SHA2-256\(stdin\)= ).*')
curl \
--request POST \
--data '{
"client_id": "'"${YOUR_CLIENT_ID}"'",
"user_id": "'"${USER_ID}"'",
"expires": "'"${EXPIRES}"'",
"signature": "'"${SIGNATURE}"'"
}' \
https://api.mpin.io/otp
# Response Example
{
"ciphertext": "iyZwAfPBnP8Q1ViTeBbXf8DFjm1A08AFlKKkB9KlJwHodmWEXJKYRpeB6eosbJvGT0MpIsb4Ssc0fB9kX3OdxA==",
"tag": "cm+1V4/WBs+DyAZg7RZS/g==",
"iv": "UlAMbRE2iw1H/yuo"
}
The OTP and expiration are AES-GCM encrypted. ‘ciphertext’, ’tag’ and ‘iv’ are base64 encoded.