Skip to main content

Core operations

Introduction​

On this page, you can learn about the different core operations that you can make with the SDK.

The activate and authentication processes are divided into multiple steps, which are performed as individual method calls on a controller.

Most calls are asynchronous, and the application is required to provide a block of code to be executed once each call has finished.

Activation​

Overview​

Activation is the first thing that your application will guide your end-user through when using Encap.

This process creates a link between your end-user's device and the Encap authentication server. This will later be used to establish trust.

To activate the end-user's device, your application will invoke three methods on the Controller in succession. The process is as follows:

  1. Optional: Retrieve settings from the Encap server, such as activation code length and type.
  2. Register the end-user's device on Encap server. The Encap server will then pass information back which the API will use to establish trust.
  3. Activate the registration, using a selected authentication method and the information that was passed back in the previous step.
Note

Following these steps, the registration can now be used to authenticate the end-user that created it.

How to implement​

Retrieve settings from Encap server (optional)​

To begin the process, you can invoke loadConfig().

Note

It will return a LoadConfigResult object with information about the activation code length and type, so that the app can present the right keyboard and UI to be input.

Although this call is optional, it can can improve the end-user's experience.

Register the end-user's device on the Encap server​

  1. Run the startActivation() operation.
  2. If the startActivation() operation is successful, then a StartActivationResult object is returned. This contains getAuthMethodsForActivation(), which is a list of authentication methods (AuthMethod) available for the device.
    • The list of authentication methods is filtered so that only those configured for this applicationId and enabled on the device are returned.
    • If more than one method is available, your app may let the end-user choose what authentication method to use.

Activate the registration​

Once the startActivation() operation has been completed successfully, you can finish the process. To do this, run the finishActivation() operation with the desired authentication method.

Use the correct type of ActivationParameter for the authentication method, and fill in the required data.

Explore supported authentication methods

For supported authentication methods and additional details, see the Authentication methods page in our Encap SDK developer documentation.

Note

The device as an authentication method (AuthMethod.DEVICE) will always be activated when activating a two-factor authentication method, such as PIN and Biometric Prompt.

Example: An activation
// The activation code should come from another source, such as a web page.
controller.startActivation(activationCode, object : AsyncCallback<StartActivationResult> {
    override fun onFailure(errorCodeException: ErrorCodeException) {
        // Handle the failure.
    }
    override fun onSuccess(result: StartActivationResult) {
        // Ready to continue to finishActivate. See result on how to proceed.
        val activationParameter = ActivationParameter() // Use the right type here for the auth method you want.
        controller.finishActivation(activationParameter, object : AsyncCallback<FinishActivationResult> {
            override fun onFailure(errorCodeException: ErrorCodeException) {
                // Handle the failure.
            }
            override fun onSuccess(result: FinishActivationResult) {
                // The auth method is activated.
            }
        })
    }
})

Fetch the registrationId​

After a successful activation, the registrationId is stored on the controller.

Example: Fetch the registrationId
controller.registrationId
Note

The registrationId is the same as the deviceId and device_id which is used in the REST APIs.

Authentication​

Overview​

Authentication is a process used to prove that the current end-user is the same as the one who performed the initial activation.

To authenticate the end-user, your application will invoke two methods on the Controller in succession. The process is as follows:

  1. Identify who your end-user claims to be to the Encap server.
  2. The Encap server sends a challenge to the client API and a response is calculated.
  3. If the authentication succeeds, then the Encap server has indicated trust that you are interacting with the correct end-user.

How to perform an authentication​

Start the authentication​

To begin the process, you need to run the startAuthentication() operation.

If the startAuthentication() operation is successful, then a StartAuthenticationResult object is returned. This has the following methods:

Finish the authentication​

  1. Once the startAuthentication operation has been completed successfully, you can finish the process by running the finishAuthentication() operation.
    • You have to pass in the desired AuthParameter for one of the authentication methods returned from getAuthMethodsForAuthentication().
  2. If the authentication operation is successful, then a FinishAuthenticationResult object is returned.
Example: An authentication
controller.startAuthentication(object : AsyncCallback<StartAuthenticationResult> {
    override fun onFailure(errorCodeException: ErrorCodeException) {
        // Handle the failure.
    }
    override fun onSuccess(result: StartAuthenticationResult) {
        // Ready to continue to finishAuthenticate. See result on how to proceed.
        val authParameter = AuthParameter() // Use the right type here for the auth method you want.
        controller.finishAuthentication(authParameter, object : AsyncCallback<FinishAuthenticationResult> {
            override fun onFailure(errorCodeException: ErrorCodeException) {
                // Handle the failure.
            }
            override fun onSuccess(result: FinishAuthenticationResult) {
                // Successfully authenticated with auth method.
            }
        })
    }
})

Add or update​

Overview​

The addOrUpdate operation enables you to:

  • Add (activate) another authentication method to an existing registration.
  • Update an existing authentication method using the same authentication method. This is a special use case for updating the PIN.

Example use case​

Your end-user wants add another authentication method to their existing registration. For example, they want to activate both the PIN and the Biometrics authentication methods.

To do this, you could:

  1. Activate the first authentication method (PIN) as described in the PIN activation section on our Authentication methods page.
  2. Activate the second authentication method (Biometrics) from within your app using the addOrUpdate operation.

How to implement​

Add another authentication to an existing registration​

  1. Activate the PIN as described in the PIN activation section on our Authentication methods page.
  2. The end-user activates Biometrics in your app by calling startAddOrUpdate.
  3. If the operation is successful, then a StartAddOrUpdateResult object is returned, similar to the result from the StartAuthentication() operation.
  4. Use the getAllowedAuthMethodsToActivate() parameter to select which authentication method to add, and look at getAllowedAuthMethodsForAuthentication to find an authentication method that is supported for authenticating in this case.
  5. Once the start call has been successfully executed, call finishAddOrUpdate with the AuthParameter for the authentication method that you want to authenticate with, and the ActivationParameter for the authentication method you want to activate.
Find activation and authentication parameters

To find the right activation parameters (ActivationParameter) and authentication parameters (AuthenticationParameter), see the Authentication methods page in our Encap SDK developer documentation.

  1. Upon a successful result, the new authentication method has now been activated and is ready to be used to authenticate the end-user.
Note

A single-factor authentication method cannot be used to add a two-factor authentication method.

You need to configure on the server which two-factor authentication methods can be used to add other two-factor authentication methods.

Other use cases

Another common use case is to update the end-user's PIN. You can read more about this in the Add or update (change PIN) section on our Authentication methods page.

Example: An add or update
controller.startAddOrUpdate(StartAddOrUpdateParameter(), object : AsyncCallback<StartAddOrUpdateResult> {
    override fun onFailure(errorCodeException: ErrorCodeException) {
        // Handle the failure.
    }
    override fun onSuccess(result: StartAddOrUpdateResult) {
        // Ready to continue to finishAuthenticate. See result on how to proceed.
        val authParameter = AuthParameter() // Use the right type here for the auth method you want.
        val activationParameter = ActivationParameter() // Use the right type here for the auth method you want.
        controller.finishAddOrUpdate(authParameter, activationParameter, object : AsyncStateChangedCallback<FinishAuthenticationResult> {
            override fun onFailure(errorCodeException: ErrorCodeException) {
                // Handle the failure.
            }
            override fun onSuccess(result: FinishAuthenticationResult) {
                // Successfully added auth method to registration.
            }
            override fun onStateChanged(state: EncapController.State) {
                // Possibility to update UI.
            }
        })
    }
})

Deactivate​

Overview​

The Controller provides two different deactivation methods.

  • Deactivate all authentication methods. This could be useful if:
    • Your end-user no longer wants to have an account in your app and wants their data deleted.
  • Deactivate a specified authentication method. This could be useful if:
    • Your end-user no longer wants to use Biometrics. Your app could then allow the end-user to deactivate that authentication method.
    • Your app no longer wants to support an authentication method. Your app could then call deactivate on that authentication method method.

      Note: Typically, you may consider to rewrite the app instead, so that this does not end up in the flow.

You may require deactivation or reactivation if the end-user forgets the PIN from their first activation. The scenario will then be identical to that of a first time activation.

How to implement​

Deactivate the registration​

Run the deactivate method to delete all registration data for the given registration, including all of the authentication methods.

  • If the localOnly parameter is set to false, then the registration is removed both from the Encap server and locally.
  • If the localOnly parameter is set to true, then the registration will only be removed locally.
Our recommendation

It is advised to always try to deactivate towards the server.

If the server is down or an other abnormality prevents you from deactivating towards the server, you can perform a local deactivation as a fallback.

Example: A deactivation
val deactivateOnlyLocally = false
controller.deactivate(deactivateOnlyLocally, object : AsyncCallback<DeactivateResult> {
    override fun onFailure(errorCodeException: ErrorCodeException) {
        // Handle the failure.
    }
    override fun onSuccess(result: DeactivateResult) {
        // Successfully deactivated.
    }
})

Deactivate a specified authentication method​

  1. Run the deactivate(AuthMethod,...) method to deactivate a specific authentication method. The registration will stay intact.
  2. The specified authentication method (authMethod) is removed both from the Encap server and locally.
Limitations

The device as an authentication method (AuthMethod.DEVICE) is used for authentication towards the server, and cannot be deactivated by this method.

Example: Deactivate a specified authentication method
controller.deactivate(AuthMethod.DEVICE_PIN, object : AsyncCallback<DeactivateResult> {
    override fun onFailure(errorCodeException: ErrorCodeException) {
        // Handle the failure.
    }
    override fun onSuccess(result: DeactivateResult) {
        // Successfully deactivated.
    }
})

Cancel session​

Overview​

You can use the cancelSession operation to cancel the activation or authentication session on the server.

For example, you could use this when the client has been notified of a new transaction, but the user rejects it by pressing the cancel button.

How to implement​

  1. Run the cancelSession() operation.
  2. The current activation or authentication session will now be cancelled on the server.
Example: Cancel a session
controller.cancelSession(object : AsyncCallback<CancelSessionResult> {
    override fun onFailure(errorCodeException: ErrorCodeException) {
        // Handle the failure.
    }
    override fun onSuccess(result: CancelSessionResult) {
        // Successfully cancelled session.
    }
})
On this page