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:
- Send your access key or intent token in the Authorization Bearer token header. For more information on the intent token, see Intent endpoint.
- Optionally, set the
channel
parameter toapp
. If thechannel
parameter is not configured, the system defaults toapp
. - Optionally, link the user with the
username
or theuserId
parameter. You can only use theuserId
parameter if the user already exists. TheuserId
can be found in the registration HTTP response.Storing the User IDStore the
userId
in your own systems for further reference, such as linking the user to your internal records in backend systems. By setting ausername
, 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 ausername
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 ImpersonationTo prevent impersonation, ensure you only link users to your backend records after strongly authenticating them first.
HTTP request examples
- cURL
- Python 3
curl "https://$instance.mauth.nevis.cloud/api/v1/users/enroll" \
-XPOST \
-H "Authorization: Bearer $access_key" \
-H 'Content-Type: application/json' \
-d '{ "username": "u12345" }'
data = {'username': 'u12345'}
resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/users/enroll',
headers = {'authorization': f'Bearer {access_key}'},
json = data)
print(resp.json())
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"
}
}
Display the QR code and deep link
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 thesrc
attribute of animage
HTML element. - Deep link: data from the
enrollment.appLinkUri
field added to thehref
attribute of ana
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:
Send the
statusToken
that was retrieved during the registration operation.- 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
- cURL
- Python 3
# Set $statusToken
curl "https://$instance.mauth.nevis.cloud/api/v1/status" \
-XPOST \
-H 'Content-Type: application/json' \
-d "{ \"statusToken\": \"$statusToken\" }"
data = {'statusToken': 'eyJhb...lc3g'}
resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/status', json = data)
print(resp.json())
HTTP response examples
- Status is pending
- Status is succeeded
- Status is failed
- Status is unknown
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"
}
200 OK
: Succeeded - The operation was successfully confirmed by the user
{
"transactionId": "b7d44592-91f3-4f4b-9e37-202a3061edc3",
"status": "succeeded",
"userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
"username": "Userxyz123",
"token": "eyJhb...Fl9bpEXGGw",
"createdAt": "2020-10-09T12:52:48Z",
"lastUpdatedAt": "2020-10-09T12:52:48Z"
}
412 Precondition Failed
: The transaction was aborted or timed out
{
"transactionId": "b7d44592-91f3-4f4b-9e37-202a3061edc3",
"status": "failed",
"userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
"username": "Userxyz123",
"token": "eyJhb...Fl9bpEXGGw",
"createdAt": "2020-10-09T12:52:48Z",
"lastUpdatedAt": "2020-10-09T12:52:48Z"
}
404 Not Found
: The provided status token is not known
{
"status": "unknown"
}
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:
- Send your access key in the Authorization Bearer token header.
- Add your token that you want to verify.
HTTP request examples
- cURL
- Python 3
# Set $token
curl "https://$instance.mauth.nevis.cloud/api/v1/introspect" \
-XPOST \
-H "Authorization: Bearer $access_key" \
--data-urlencode "token=$token"
data = {'token': 'eyJhb...lc3g'}
resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/introspect',
headers = {'authorization': f'Bearer {access_key}'},
data = data)
print(resp.json())
HTTP response examples
- Active and valid access key
- Valid transaction token
- Valid status token
- Valid intent token
- Invalid token
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/"
}
200 OK
: Valid transaction token
{
"active": true,
"iat": 1654759374000,
"sub": "fc6bf4bb-9f46-48a9-95d6-91051a3d6468",
"aud": "transaction",
"iss": "https://{instance}.mauth.nevis.cloud/"
}
200 OK
: Valid status token
{
"active": true,
"iat": 1662625372000,
"sub": "29886449-532e-4de7-923d-845e94b81762",
"aud": "status",
"iss": "https://{instance}.mauth.nevis.cloud/",
"jti": "fdc3e23e-9ec8-4375-9b13-9a586270a9cd"
}
200 OK
: Valid intent token
{
"iat": 1662626062,
"exp": 1662626662,
"aud": "intent",
"iss": "https://{instance}.mauth.nevis.cloud/",
"sub": "0afb658e-9536-430f-a69b-d53a7a603be1",
"scope": "enroll:sms,app"
}
200 OK
: Invalid token
{
"active": false
}