Create Verification

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

Endpoint Supported methods Full URL
/verification POST https://api.mpin.io/verification

# 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>"
}

Some terminal emulators display special characters like & as their Unicode codes (e.g., \u0026) in JSON output. To copy the verificationURL for testing, use jq: curl ... | jq ..

# Errors

# INVALID_REQUEST_PARAMETERS

Missing or invalid parameters from the request. You can see the affected parameter(s) in the context of the error. For information about the possible parameters, see the Parameters section above.

{
  "error": "INVALID_REQUEST_PARAMETERS",
  "info": "Missing or invalid parameters from the request.",
  "context": {
    "params": "userId"
  }
}

# INVALID_REQUEST_AUTHORIZATION

The authorization header is malformed or contains invalid credentials. For more information about the format of the header, see the Endpoint Authentication section above.

{
  "error": "INVALID_REQUEST_AUTHORIZATION",
  "info": "The authorization header is malformed or contains invalid credentials."
}

# INVALID_VERIFICATION_METHOD

You must enable the Custom verification method in the MIRACL Trust Portal to use this API. To do that, go to the User Verification section in your Projects’ settings and select Custom from the Verification Method dropdown.

{
  "error": "INVALID_VERIFICATION_METHOD",
  "info": "Verification method not allowed in your project configuration. "
}

# INVALID_REQUEST_BODY

The request payload needs to be a valid JSON.

{
  "error": "INVALID_REQUEST_BODY",
  "info": "The request payload is invalid JSON."
}