Mobile Enrollment

Before you can complete this part of the integration make sure you have:

  • Configured the Android SDK
  • Have developer access to the Pinn REST API

Creating Users

Before a user can enroll or authenticate with Pinn you must first create a Pinn User to associate with their account. This is done by calling our API to create a user, then attaching the unique identifier returned to your system's user record. We recommend that you create the Pinn user and attach the identifier whenever a new user registers for an account, or for existing users prior to their enrollment. It is perfectly okay to create the Pinn user and enroll at a later point in an opt-in fashion. For more details look at the API reference documentation on Create User.


Authorization: Bearer sk_UB8hITybDSwMBVSEBGYV8ZqYAaabHS5e


    "created_at": 1547227644,
    "devices": "/users/usr_xB8hIUJ1XiIBh0VSABGvUHYl/devices",
    "last_auth": null,
    "last_enroll": null,
    "metadata": {},
    "object": "user",
    "report": "/users/usr_xB8hIUJ1XiIBh0VSABGvUHYl/report",
    "status": "valid",
    "updated_at": 1547227644,
    "user_id": "usr_xB8hIUJ1XiIBh0VSABGvUHYl"

The user_id returned should be retained alongside your own end user in your database. This allows for your backend to easily lookup the Pinn User anytime your user resource is queried. Now that you have a Pinn user created, you can move on to the next step.

Creating an Enrollment Key

Enrollment keys are short-lived keys that allow users to enroll with Pinn. They originate and are authorized by your backend. Our mobile client SDKs handle the enrollment key transparently. Your web server simply needs to call the Pinn API to create a new enrollment key, which is than returned to your mobile application. Once your mobile application has received a newly minted enrollment key, the enrollment process can begin.

On your web server, provide an endpoint that will provide the enrollment authorization logic (rules that dictate if an end user is permitted to enroll), and call our API to create and return the enrollment key. The following is a code snippet that will permit any user with a valid session to enroll. For more details, check out our API Reference Documentation for creating Enrollment Keys.

import requests

@app.route('/enrollment_keys', methods=['POST'])
def enrollment_keys():
	r ='',
			  json={'user_id': current_user.pinn_user_id},
			  headers={'Authorization': 'Bearer <your_secret_key>'})
	if r.ok:
	    return jsonify(r.json())
	    # Handle error

Your backend does not need to worry about the contents of the JSON returned from creating an enrollment key. Our mobile SDKs handle the response directly in order to perform enrollment. After preparing your server, you'll be ready to consume the key and can start by pointing our mobile SDK to the endpoint you setup.

Consuming the Enrollment Key

Now that your backend service is able to produce enrollment keys, you need to implement the EnrollmentKeyProvider protocol within your own Android app. This provider interface allows Pinn to handle the Enrollment Key response directly, and abstracts away the networking details of the enrollment process away from your app.

 * Makes a request to a backend API for an enrollment key
public void createKey(Listener listener) {
    // Using Retrofit and RxJava for asynchronous responses
            .subscribe((ResponseBody response) -> {
                throwable -> {
                    if (throwable instanceof HttpException) {

Device Enrollment

Now that your app can retrieve an enrollment token generated from you backend, you can perform device enrollment. Best practices are to do this immediately after registration or when logging in on a device for the first time.

                  new Pinn.EnrollDeviceListener() {
    public void deviceEnrolled() {
        // Device was successfully enrolled

    public void error(String s) {
        // Handle error



Device enrollment will register a device to a given Pinn user. Completing this enables the device to authenticate using any local authentication methods.

Once device enrollment is complete users will be enabled to do any on-device factors for authenticating, such as local passcode and local biometric authentication.

Palm Enrollment

In order to enable palm authentication you must present the palm enrollment flow to your end users. This is done by requesting and launching an Android Intent that will launch the Palm Enrollment Flow. The following can be done in an Activity or Fragment.

Intent intent = Pinn.generateEnrollmentIntent(getActivity());
// Filter out other response codes when OnActivityResult is invoked
int enrollRequestCode = 1234;
startActivityForResult(intent, enrollRequestCode);


public void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    // Filter our for the request code that was set earlier
   switch(requestCode) {
       case enrollRequestCode:
           if (resultCode == Pinn.Result.ENROLL_SUCCESS) {
               // Successful palm enrollment

This will initiate the Palm Enrollment experience. After your end user has completed the workflow, they will be ready to authenticate using any of the factors Pinn offers.


Now that you have enrollment working, you can setup your application for authentication.



We are here to help! Contact us with any development related questions at and we'll reach back in a timely manner.