Skip to main content

Register your mobile app

In this process, you are registering your mobile app authenticator. If the user does not exist yet, a new user is created.

The following diagram shows the end-to-end sequence of a registering a mobile app authenticator. This sequence creates a new user as well. The steps that must be performed to integrate the Authentication Cloud into your application are in bold.

Send an HTTP request to the registration endpoint​

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

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/users/enroll 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. Optionally, set the channel parameter to app. If the channel parameter is not configured, the system defaults to app.
  3. Optionally, link the user with the username or the userId parameter. You can only use the userId parameter if the user already exists. The userId can be found in the registration HTTP response.
    Storing the User ID

    Store the userId in your own systems for further reference, such as linking the user to your internal records in backend systems. By setting a username, it is possible to do two-way linking between your system and the Authentication Cloud.

    Use unique static information for the username parameter. To link a user to your internal systems, you might use, for example, an internal customer ID or employee ID, and provide that as a username in the user registration request. It is important to use information that does not change over the life cycle of a user.

    Do not use a username with any Personally Identifiable Information (PII). For example, an email address is not recommended because it is not only PII data, but it also might change over the lifecycle of a user.

    Preventing User Impersonation

    To prevent impersonation, ensure you only link users to your backend records after strongly authenticating them first.

HTTP request examples​

cURL code sample to register a user with a username for two-way linking
curl "https://$instance.mauth.nevis.cloud/api/v1/users/enroll" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  -H 'Content-Type: application/json' \
  -d '{ "username": "u12345" }'

HTTP response example​

201 Created: Register mobile app

{
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "username": "u12345",
  "status": "new",
  "createdAt": "2020-10-09T12:13:11.845958Z",
  "updatedAt": "2020-10-09T12:13:11.845958Z",
  "authenticators": [],
  "enrollment": {
    "transactionId": "67cae36e-e3d5-4d67-9aa6-ab7ae3050576",
    "statusToken": "eyJhbGciO...PxOZZYow",
    "qrCode": {
      "type": "image/png",
      "size": 300,
      "dataUri": "data:image/png;base64,iVBO...YII"
    },
    "appLinkUri": "https://{instance}.mauth.nevis.cloud/open?dispatchTokenResponse=eyJub...IxIn0"
  }
}

Once the registration operation is started, Authentication Cloud generates a qrCode and an appLinkUri, and returns it within the registration response, together with a unique userId, a 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 registration 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.

After using the QR code or the deep link, the user can authenticate themselves, for example, with PIN or biometric data. The authentication response includes a public key, and the Authentication Cloud stores this public key representing the authenticator, against the user object.

Start polling the status endpoint​

To verify the success of the registration 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 registration 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.

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