Skip to main content

Sign transactions with QR code or deep link

Transaction signing is an operation that is initiated within an already authenticated session. This operation is very similar to authentication, but a transaction signing can be initiated by a privileged user (such as a helpdesk user), not only by the end user.

For approval operations with QR code or deep link, you can use usernameless authentication as well.

info

The Nevis Mobile Authentication SDK allows the use of the fetch channel to get a list of ongoing operations for a specific device. This ensures that if there is intermittent or network lag, or if the push service is unavailable, users can always be provided with the request they generated. For more information, see the relevant sections in the documentation for Nevis Mobile Authentication SDK and nevisFIDO.

The following diagram shows the end-to-end sequence of signing a transaction with QR code or deep link. The steps that must be performed to integrate the Authentication Cloud into your application are in bold.

Send an HTTP request to the approval endpoint​

For detailed information on the HTTP request parameters and response fields, see the Approval endpoint page of the API reference documentation.

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/approval call with your instance ID, and configure the HTTP request as follows:

  1. Send your access key or intent token in the Authorization Bearer token header. For more information on the intent token, see Intent endpoint.
  2. Set the channel parameter to app.
  3. Set the username or userId parameter. Skip this step if you are using usernameless authentication.
  4. Set the prompt parameter to true. This creates a flag to request the user to actively accept or deny the authentication.
  5. Configure the message parameter. This displays a notification message on the user device.

    You can format the message with a limited set of supported HTML tags. To enable text formatting, enclose the transaction confirmation text in the <html></html> HTML tags. If you include an unsupported tag, such as <p> or <div>, or add any attribute to a tag, you will receive an HTTP 400 Bad Request response. The following tags and formatting options are supported:

    • <b></b>: bold
    • <br>: line break
    • <em></em>: emphasis
    • <i></i>: italic
    • <strong></strong>: strong
    • <u></u>: underline
  6. To sign the transaction with a specific authenticator, set the authenticatorId parameter. If this parameter is not configured, the default authenticator is used, which is the most recently registered authenticator. Using authenticatorId=* means that any registered authenticator can be used for the operation.

HTTP request examples​

Code sample for transaction signing using QR code or deep link
  curl "https://$instance.mauth.nevis.cloud/api/v1/approval" \
    -XPOST \
    -H "Authorization: Bearer $access_key" \
    -H 'Content-Type: application/json' \
    -d "{ \"channel\":\"app\",
          \"prompt\":\"true\",
          \"username\": \"$username\",
          \"message\":\"$message\" }"

HTTP response example​

{
  "transactionId": "9ede8ca8-bb5f-47f1-9d3e-f14500a3cab6",
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "statusToken": "eyJhb...lc3g",
  "qrCode": {
    "type": "image/png",
    "size": 300,
    "dataUri": "data:image/png;base64,iVBORw0...U5ErkJggg"
  },
  "appLinkUri": "https://{instance}-app.mauth.nevis.cloud/open?dispatchTokenResponse=eyJub...AQIn3"
}

Once the authentication operation is started, Authentication Cloud generates a qrCode and an appLinkUri, and returns it within the approval response, together with a the transactionId and a statusToken.

To ensure that the QR code and the deep link is displayed on the user device, you need to extract data from the authentication response. Use the response as follows:

  • QR code: data from the enrollment.qrCode.dataUri field added to the src attribute of an image HTML element.
  • Deep link: data from the enrollment.appLinkUri field added to the href attribute of an a HTML element.

The QR code and the deep link include a dispatchToken.

## Start polling the status endpoint​

To verify the success of the approval operation, start polling the status endpoint from your frontend application. The recommended polling interval is 1.5 seconds. Depending on your circumstances, such as user needs and production system capabilities, you might need to adjust the wait times between two polling cycles.

For detailed information on the HTTP request parameters and response fields, see the Status endpoint page of the API reference documentation.

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/status call with your instance ID, and configure the HTTP request as follows:

  1. Send the statusToken that was retrieved during the approval operation.

  2. Poll for the status as long as status is pending.

When you receive a succeeded, failed, or unknown status, you can react accordingly. If the status is succeeded, continue with verifying the operation from your backend application.

In case of usernameless authentication, you can use the status endpoint to get the identifier of the authenticated user. In this case, the user is not known until the authentication is successfully finished, thus the intermediate status response does not contain a userId. After the user is successfully authenticated, the userId is included in the status response.

After using the QR code or the deep link, the user can authenticate themselves, for example, with PIN or biometric data. The authentication response to the Authentication Cloud includes a signed message. The response is validated with the previously stored public key.

HTTP request examples​

Code sample for status polling
# Set $statusToken
curl "https://$instance.mauth.nevis.cloud/api/v1/status" \
  -XPOST \
  -H 'Content-Type: application/json' \
  -d "{ \"statusToken\": \"$statusToken\" }"

HTTP response examples​

200 OK: Pending - The operation is still waiting for confirmation by the user

{
  "transactionId": "b7d44592-91f3-4f4b-9e37-202a3061edc3",
  "status": "pending",
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "username": "Userxyz123",
  "token": "eyJhb...Fl9bpEXGGw",
  "createdAt": "2020-10-09T12:52:48Z",
  "lastUpdatedAt": "2020-10-09T12:52:48Z"
}

Verify the operation​

Once the authentication is successful and you receive the server response, verify the operation. Use of the following verification methods:

  • HTTP request to the status endpoint
  • HTTP request to the introspect endpoint

Send an HTTP request to the status endpoint​

By calling the status endpoint from your backend application, you request Authentication Cloud to verify the validity and the authenticity of the operation. This is done by using the statusToken from the previous HTTP response.

For detailed information on the HTTP request parameters and response fields, see the Status endpoint page of the API reference documentation.

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/status call with your instance ID and include the statusToken that was retrieved during the operation.

Send an HTTP request to the introspect endpoint​

By calling the introspect endpoint from your backend application, you request Authentication Cloud to verify the validity and the authenticity of the user. This is done by using the transaction token returned by the status endpoint.

For detailed information on the HTTP request parameters and response fields, see the Introspect endpoint page of the API reference documentation.

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/introspect call with your instance ID, and configure the HTTP request to the introspect endpoint as follows:

  1. Send your access key in the Authorization Bearer token header.
  2. Add your token that you want to verify.

HTTP request examples​

cURL code sample for checking the validity and authenticity of a token
# Set $token
curl "https://$instance.mauth.nevis.cloud/api/v1/introspect" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  --data-urlencode "token=$token"

HTTP response examples​

200 OK: Active and valid access key

{
  "active": true,
  "iat": 1642436165000,
  "sub": "c8edb1d1-6dac-470f-b2fb-c25277a5c5b6",
  "aud": "api",
  "iss": "https://{instance}.mauth.nevis.cloud/"
}