Mobile-First Authentication

Mobile Token and PowerAuth Cloud Onboarding

Mobile Token

The step-by-step manual for activation and usage of Mobile Token. For more details please see the following sections of documentation:

• System Integration
• Activation states and flow
• Computing and Validating Signatures
• Operations Configurations
• PowerAuth Cloud API - General Principles
• Administrative Services
• Auditing Services
• Authentication Services
• Communication Services
• Operations Services
• Registrations Services

Environment Setup

The environment is provisioned with pre-created account credentials and basic PowerAuth configuration. All credentials for the environment will be shared with your appointed persons.

The shared credentials contain the following:

• admin user and password,
• integration user and password,
• URL to the endpoint,
• application configuration data.

Please note that, generally, credentials can be reset but not revealed – e.g., in case of forgotten passwords.

Creating Integration Users

You can create additional users via API. Those users are called Integration users, and the purpose is to segregate a user needed for admin API from the user for standard operations.

The API example:

POST /powerauth-cloud/admin/users

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/System Users/createUser

Payload:

{
  "username": "<client-name>-integration-user"
}

• username - new integration user username

Creating Application

We have already prepared application <client-name>-mobile-token in the environment. You can create additional applications via API at your convenience. The integration user has to be assigned to the created application.

The API for application creation:

POST /powerauth-cloud/admin/applications

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Applications/createApplication

Payload:

{
  "id": "<client-name>-mobile-token"
}

• id – ID of the created application.

The call returns the credentials needed for Mobile Token setup. For Mobile Token, this will be handled by the Wultra team. In the case of SDK development, the credentials have to be compiled into your mobile app.

The API for assigning an integration user to the application:

POST /powerauth-cloud/admin/users/<client-name>-integration-user/applications/<client-name>-mobile-token

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/System%20Users/addAppAccessToUser

Payload

{
  "username": "<client-name>-integration-user",
  "appId": "<client-name>-mobile-token"
}

• username – integration user username.
• appId – created application ID.

Mobile Token Installation and Configuration

Installing Wultra Key DEMO App

1. Install Wultra Key DEMO app
   • iOS version – TestFlight
   • Android version – Google Play

Configuring Wultra Key DEMO App with an Environment

1. Tap Settings –> Server environment –> New environment
2. Select Paste environment JSON
3. Insert environment JSON
4. Restart the app and use it with the provided backend APIs (environment configured by inserting the environment JSON).

Mobile Token Activation

This section covers Mobile Token activation and basic token status management.

Creating QR Activation Code

Generate the QR code (one of the activation options) needed to activate the device. The QR code is typically shown in your web application.

Generate QR code via an API endpoint:

POST /powerauth-cloud/v2/registrations

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Registrations/createRegistration

Payload:

{
  "userId": "{userId}",
  "appId": "<client-name>-mobile-token"
}

• userId – use your end user identifier.
• appId – use <client-name>-mobile-token.

In the response, you will get two attributes: activationQrCodeData and registrationId.

• activationQrCodeData – data for QR code generation. To generate the QR code, you can copy and paste the string to any QR Code Generator
• registrationId – this value represents the registered device for the user, and you will need to use it in subsequent operations, so please note it for later use

Using QR Activation Code

Open the application, tap More activation options –> In the internet banking –> Scan the QR code, and scan the QR code. Please keep in mind that the activation has limited validity. By default, it is set to 2 minutes.

The mobile application will show a dialog that displays the confirmation code. This is for scenarios where the user has to confirm the activation in Internet banking or at a branch.

Checking Activation Status (Optional)

To check the activation status, use the API endpoint:

GET /powerauth-cloud/v2/registrations/

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Registrations/getRegistrationList

Query parameters:

{
  "registrationId": "{registrationId}"
}

The registrationId parameter in the query has to match the registrationId used in the previously created registration.

Removing Activation

The registration can be removed at this stage – e.g., when a user cancels the registration process. The registration in CREATED and PENDING_COMMIT can be removed by an API endpoint:

DELETE /powerauth-cloud/v2/registrations/${registrationId}

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Registrations/deleteRegistration

Payload:

{
  "registrationId": "{userId}",
  "externalUserId": "{any id of your employee}"
}

• registrationId – ID created previously during the Creating QR Activation Code step.
• externalUserId – you can insert any ID you want to associate with the registration, e.g., an ID of an external user who created this change, for example the admin or call center operator.

Commiting Activation

Now commit the activation. This part is designed for your onboarding process and KYC to kick in, and the Power Auth server is waiting for an external call to “commit” the registration to an active state.

To commit the activation, i.e. finalize the activation, use the API endpoint:

POST /powerauth-cloud/v2/registrations/${registrationId}/commit

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Registrations/commitActivation

Payload:

{
  "registrationId": "{userId}",
  "externalUserId": "{any id of your employee}"
}

• registrationId – ID created previously during the Creating QR Activation Code step.
• externalUserId – you can insert any ID you want to associate with the registration, e.g., an ID of an external user who created this change, for example the admin or call center operator.

Now the mobile application informs you that it is ready to serve authenticated requests.

Blocking and Unblocking Activation

Once the registration has been committed, it cannot be simply removed by the verb DELETE, but you can still change the registration status. Typically, when you wish to block (or unblock the device) or an internal process removes the registration entirely.

API endpoint:

PUT /powerauth-cloud/v2/registrations/${registrationId}

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Registrations/updateRegistrationState

Payload:

{
  "change": "BLOCK",
  "blockReason": "The reason for blocking",
  "externalUserId": "{any id of your employee}"
}

• change - the state to which the registration should change.
• blockReason - reason for blocking the registration.
• externalUserId – you can insert any ID you want to associate with the registration, e.g., an ID of an external user who created this change, for example the admin or call center operator.

Operation Management

Creating and approving the operations is the main functionality of the Wultra Mobile Token.

Invoking Operation

There are two operation templates prepared in the demo environment: login and payment.

Login

The operation login can be invoked via an API endpoint:

POST powerauth-cloud/v2/operations

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Operations/createOperation

Payload:

{
  "userId": "{userId}",
  "template": "login",
  "language": "en"
}

• userId – userId created in the registration step.
• template – you can use pre-defined operation templates login or payment.
• language – for localization purposes, only English is available in the demo environment, this is the language of first push notification, otherwise the localization is driven by the setting of the mobile app.

Payment

The call for payment has a slightly different payload as there are more parameters defined in the template:

POST powerauth-cloud/v2/operations

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Operations/createOperation

Payload:

{
  "userId": "{userId}",
  "template": "login",
  "language": "en",
  "parameters": {
    "amount": "1000000000.00",
    "currency": "EUR",
    "iban": "CZ5508000000001234567899"
  }
}

• parameters – this section is defined per template, i.e. new template has to be configured for different parameters. In the response, you will receive operationId attribute. The attribute is needed for subsequent operation processing.

Confirming Operation

Operation is confirmed (or rejected) in Mobile Token. When you invoke the create operation API and open the application, it will ask you to confirm the operation via PIN or Biometry.

Checking Operation Status (Optional)

To check the operation status you can poll the result via an API endpoint:

GET /powerauth-cloud/v2/operations/${operationId}

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Operations/getOperation

Query parameters:

{
  "operationId": "{operationId}"
}

• operationId – operationId received during the creation of the operation.

Wultra PowerAuth system can perform callbacks, so in a real-life scenario you typically combine callback with polling to get immediate response via callback for the best user experience and polling as a fallback.

Removing Operation (Optional)

You can remove any pending operation if required by your business logic.

Removal is invoked via an API endpoint:

DELETE /powerauth-cloud/v2/operations/${operationId}

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Operations/cancelOperation

Payload:

{
  "operationId": "{operationId}"
}

• operationId – ID of the operation to be removed.

Push Notifications

For a good user experience, PowerAuth actively sends push notifications when a user should confirm an operation. The PowerAuth API also allows sending custom push notifications.

A push notification can be sent via an API endpoint:

POST /powerauth-cloud/v2/messages/send

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Push Notifications/applicationDetail

Payload:

{
  "userId": "{userId}",
  "registrationId": "{registrationId}",
  "silent": false,
  "title": "Balance Update",
  "message": "We just updated your balance. You can review it in mobile banking.",
  "sound": "default"
}

• userId – userId created in the registration step.
• registrationId – registrationId created in the registration step. The registrationId is optional if the push notification should be sent only to a specific device.
• silent – switch if the message delivery should be announced by a push message.
• title - title of the notification
• message- content of the message

Inbox

For communication purposes – like sending news, info about new features etc., PowerAuth Cloud offers simple Inbox.

An example of an API call sending a simple message to the Inbox:

POST /powerauth-cloud/v2/inbox/messages

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Inbox/sendMessage

Payload:

{
  "userId": "{userId}",
  "type": "html",
  "subject": "Message subject",
  "summary": "Message summary",
  "body": "Message content",
  "silent": false
}

• userId – userId created in the registration step.
• type – user html of text.
• subject – message subject – used for push notification and as a headline in Mobile Token.
• summary – message summary used for the push notification.
• body – main message body displayed in Mobile Token.
• silent – switch if the message delivery should be announced by a push message.