iOS

Mobile Enrollment

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

  • Configured the iOS 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.

Request

POST https://pinnapis.com/v1/users
Authorization: Bearer sk_UB8hITybDSwMBVSEBGYV8ZqYAaabHS5e
        

Response

{
    "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'])
@login_required
def enrollment_keys():
	r = requests.post('https://pinnapis.com/v1/enrollment_keys',
			  json={'user_id': current_user.pinn_user_id},
			  headers={'Authorization': 'Bearer <your_secret_key>'})
	if r.ok:
            return jsonify(r.json())
	else:
	    # 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 PNNEnrollmentKeyProvider protocol within your own iOS 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.

import Foundation
import Pinn

class  EnrollmentKeyProvider : PNNEnrollmentKeyProvider {
	func  createKey(apiVersion: String,
			onSuccess: @escaping (NSDictionary) -> (),
    		        onError: @escaping (String) -> ()) {
		YourBackendService.shared.getEnrollmentKey(onSuccess: onSuccess, onError: onError)
	}
}
        

Here, the getEnrollmentKey request is an HTTP call to your app backend on the endpoint you previously configured in Creating and Enrollment Key. Once this is implemented, our iOS SDK will be able to perform device enrollment.

Be sure to register this Class after setting up the Pinn sdk in your App Delegate if you haven't already.

import Pinn

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Add the Pinn Setup call
    Pinn.setup(host: "pinnapis.com", publishableKey: "yourPublishableKey")
    // Register EnrollmentKey
    Pinn.setEnrollmentKeyProvider(enrollmentKeyProvider: EnrollmentKeyProvider())
}
        

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.

Pinn.shared.enrollDevice(parentViewController: self,
    onSuccess: {
        // Handle success. Optionally save enrollmentToken
},
    onError: { (error) in
        // Handle error
})
        

!

Note

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 similar to device enrollment.

Pinn.shared.presentPalmEnrollmentFlow(parentViewController: self,
    onSuccess: { (palmEnrollmentToken) in
	// Handle success. Optionally save palmEnrollmentToken
},
    onCancel: { (error) in
	// Handle error
})
        

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.

Next

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

?

Questions?

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