Cotter
  • 🚀Getting Started
  • Features & Concepts
    • 💬Sign In with Email/Phone Number
    • 🔐Sign In with Device
      • How it works
    • 🧬Sign In with WebAuthn
  • 📌Quickstart Guides
    • All Guides & Tutorials
    • HTML – Sign in with Email/Phone
    • React – Sign in with Email/Phone
    • React – WebAuthn
    • ▲ Next.js
    • Angular
    • Webflow
    • Bubble.io
    • Python SDK for a CLI
    • React Native – Sign in with Device
    • iOS – Sign in with Device
    • Flutter – Sign in with Device
  • 📘SDK Reference
    • Web
      • Sign In with Email/Phone Number
        • Customize the Form
        • Checking the email or phone before sending a verification code
        • Sending Code or Link via WhatsApp
        • Styling
        • Older SDK
          • Customize the Form
      • Sign in with Social Login
        • Getting Access Tokens from Social Login Providers
        • Github Instructions
        • Google Instructions
      • Sign In with WebAuthn
        • Register WebAuthn for a logged-in user
      • Sign In with Device
        • Steps for Pop Up Authentication Prompt
        • Advanced Customization for Login Form
        • Advanced Customization for Pop Up Authentication Prompt
      • Getting Access Token and Logged-In User Info
      • Sending Successful Form Submission
      • FAQ & Troubleshooting
    • React Native
      • Installation
      • Sign In with Device
        • Add Email/Phone Verification
        • Authenticate from a Non-Trusted Device
        • Add a new Trusted Device
        • Remove Trusted Device
      • Sign In with Email/Phone Number
      • Getting Stored OAuth Tokens and User Information
      • FAQ
      • Older SDK Versions
        • Sign in with Email/Phone
        • Sending Code via WhatsApp
        • Sign In with Device
          • Authenticate from a Non-Trusted Device
          • Add a new Trusted Device
          • Customization
    • Flutter
      • Sign In with Device
        • Add Email/Phone Verification
        • Authenticate from a Non-Trusted Device
      • Sign in with Email/Phone Number
      • Getting the Logged-in User
      • Getting OAuth Tokens
      • Signing a User Out
    • iOS
      • Sign In with Email/Phone Number
      • Sign In with Device
        • Authenticate from a Non-Trusted Device
        • Push Notification
        • Check if Trusted Device is Enrolled
        • Add a New Trusted Device
        • Remove Trusted Device
      • Older Versions
        • Biometric/Pin
    • Android
      • Sign In with Device
        • Authenticate from a Non-Trusted Device
        • Check if Trusted Device is Enrolled
        • Add a new Trusted Device
        • Remove Trusted Device
        • Customization
      • Sign In with Email/Phone Number
      • Biometric/Pin
        • Advanced Methods
        • Customization
        • Setting Strings
        • Styling
      • Older SDK Version
        • Sign In with Device
          • Authenticate from a Non-Trusted Device
    • Python (for CLI)
    • API for Other Mobile Apps or CLI
      • Verify Email/Phone Number
        • Handling URL Scheme
    • Backend: Handling Response
  • 🛡️ Protecting Your Account
    • Only Allow Your Website/App to Use Your API Key
    • Rate Limit
    • Enable reCAPTCHA to Protect Against Automated Abuse
  • 🗝️ Getting Access Token
    • Cotter's OAuth 2.0 Tokens Specification
    • Getting the Tokens
      • Get Tokens during Authentication
      • Using the Refresh Token
    • Storing and Removing Tokens
    • Renewing Expired Tokens
    • Verifying JWT Tokens
    • Requesting Custom Fields on your JWT Token
    • Older API
      • Using HTTP Requests
      • Getting the Tokens
        • During Authentication
          • During Email/Phone Verification
        • During enrolling Trusted Devices
  • 🔌API Reference
    • User API
      • User Object
    • OAuth Tokens API
      • Verify JWT Token using API (serverless)
      • Requesting Custom Claims on your Access Token
      • Older API
    • OAuth Tokens from Social Login
    • Event Object
    • Reset PIN API
  • Older API
    • Validating Cotter's Identity Token
    • Validating Cotter's Event Response
Powered by GitBook
On this page
  • Overview
  • What you're building
  • Steps
  • Step 1: Import Cotter as a dependency
  • Step 2: Setting Authentication Methods
  • Step 3: Creating a User
  • Step 4: Initialize Cotter
  • Step 5: Enroll Biometric and PIN
  • Step 6: Verify Biometrics on Transactions
  • 🎉 You're done!
  1. SDK Reference
  2. Android

Biometric/Pin

Cotter's Android SDK helps you easily add a Biometric prompt or PIN fallback to your app. This is useful for protecting transactions or sensitive information like medical records.

PreviousSign In with Email/Phone NumberNextAdvanced Methods

Last updated 4 years ago

There are major updates planned for this feature. so we can help you prepare for it.

Overview

Enabling PIN and Biometric using Cotter's Android SDK consists of:

  1. Initializing Cotter

  2. Calling functions to start Pin Enrollment and Biometric Enrollment

  3. Verify Biometric or PIN before a transaction

  4. Enabling and disabling Biometric or PIN in Settings

What you're building

Steps

Step 1: Import Cotter as a dependency

Add JitPack repository your project level build.gradle at the end of repositories.

build.gradle
allprojects {
		repositories {
			...
			maven { url 'https://jitpack.io' }
		}
	}

Add the Cotter's SDK as a dependency in your app level build.gradle .

android {
  ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

dependencies {
  ...
  implementation 'com.github.cotterapp:android-sdk:0.3.2'
}

Then sync your gradle files.

Step 2: Setting Authentication Methods

Remember to set the correct Project in the dropdown list.

Step 3: Creating a User

1. Registering a User

Your server should do this request to Cotter's server during Registration.

curl -XPOST \
-H 'API_KEY_ID: <your key id>' \
-H 'API_SECRET_KEY: <your secret key>' \
-H "Content-Type: application/json" \
-d '{"client_user_id": "<Your User Identifier (string)>"}' \
'https://www.cotter.app/api/v0/user/create'
{
  "ID": "9449e9e9-00e0-4d6b-a4b6-28c5b22b0b0f",
  "created_at": "2020-01-21T12:40:21.200727668Z",
  "update_at": "2020-01-21T12:40:21.200727668Z",
  "deleted_at": null,
  "issuer": "<your key ID>",
  "client_user_id": "<Your User Identifier (string)>",
  "enrolled": [],
  "default_method": null
}

2. Get user data

To retrieve user's data:

curl -XGET \
-H 'API_KEY_ID: <your key id>' \
-H 'API_SECRET_KEY: <your secret key>' \
'https://www.cotter.app/api/v0/user/:your_user_id'
{
  "ID": "9449e9e9-00e0-4d6b-a4b6-28c5b22b0b0f",
  "created_at": "2020-01-21T12:40:21.200727668Z",
  "update_at": "2020-01-21T12:40:21.200727668Z",
  "deleted_at": null,
  "issuer": "<your key ID>",
  "client_user_id": "<Your User Identifier (string)>",
  "enrolled": ["PIN", "BIOMETRIC"],
  "default_method": "BIOMETRIC"
}

Step 4: Initialize Cotter

You can now use the SDK to enroll and verify Biometric and PIN for the user you just created.

Initialize

In your MainActivity, initialize Cotter with API keys, Cotter's URL to use (prod/test), and your User ID.

Production Endpoint: https://www.cotter.app/api/v0

Cotter.init(
    this.getApplicationContext(),
    "https://www.cotter.app/api/v0",
    "<User ID>",
    "<API_KEY_ID>",
    "<API_SECRET_KEY>"
);

Example:

MainActivity.java
public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...

        Cotter.init(
            this.getApplicationContext(),
            "https://www.cotter.app/api/v0",
            "hello@example.com",
            "588d6f67-0981-4718-899b-bcd512de1aca",
            "w4FK6Zz0XIhtGY3o5biI");
    }
    ...

Step 5: Enroll Biometric and PIN

to enroll both Biometric and PIN, start the PinEnrollment flow in your Activity, pass in the Callback Screen, and the Event Tag. Event Tag is used for your own logging, for example, a pin enrollment event can be called "PIN_ENROLLMENT_ANDROID" to tag a pin enrollment event from an Android device.

Cotter.PinEnrollment.startFlow(view, CallBack.class, "EVENT TAG");

Example:

// Inside your app, use a button onClick that calls
// openEnroll to start the flow
public void openEnrollment(View view) {
    Cotter.PinEnrollment.startFlow(view, Dashboard.class, "PIN_BIO_ENROLLMENT");
}

How PinEnrollment looks like

After entering the PIN, the user will automatically be prompted to Enroll Biometrics if the device supports it. Entering a PIN is required as a fallback method.

Step 6: Verify Biometrics on Transactions

The PinVerification flow will automatically prompt for Biometric Verification if the user's device has an enrolled biometric, otherwise, it will fallback to entering PIN. Starting the PinVerification flow is exactly the same as starting the PinEnrollment flow.

Cotter.setOnResetPin(new PinResetInterface() {
            @Override
            public void onResetPin(User user, Callback callback) {...}
})
Cotter.PinVerification.startFlow(view, CallBack.class, "EVENT TAG");

In the verification page, there is a button called Forgot PIN . This is used to send a verification code to allow the user to reset their PIN.

setOnResetPin is used to set a callback function that will be called to reset the pin. You need to provide a function that follows the PinResetInterface. This function should call your server to initiate the PIN reset request.

When your onResetPin function is called, it should call your server, and your server needs to do the following:

  1. Based on the currently logged-in user, find out the user's Email and name

  2. Receive the response from Cotter which contains the fields success, challenge_id, challenge

  3. Call the callback.onSuccess with a JSONObject containing the following JSON object:

{
  "success": true,           // from the response from the Reset PIN API
  "challenge_id": 123,       // from the response from the Reset PIN API
  "challenge": "abcde12345", // from the response from the Reset PIN API
  "sending_method": "EMAIL",
  "sending_destination": "user@email.com"
}

Example:

// In onCreate, set the onResetPin callback
protected void onCreate(Bundle savedInstanceState) {
     Cotter.setOnResetPin(new PinResetInterface() {
        @Override
        public void onResetPin(User user, Callback callback) {
            // 1. Call your server
            // 2. Get the response from your server
            // 3. Construct a JSONObject and pass it to callback.onSuccess
            JSONObject req = new JSONObject();
            try {
                req.put("success", response.getBoolean("success"));
                req.put("challenge_id", response.getInt("challenge_id"));
                req.put("challenge", response.getString("challenge"));
                req.put("sending_method", sendingMethod);
                req.put("sending_destination", sendingDestination);
            } catch (Exception e) {
                callback.onError(e.toString());
            }
    
            callback.onSuccess(req);
        }
    });
}

// Inside your app, use a button onClick that calls
// openPinVerification to start the flow
public void openPinVerification(View view) {
    Cotter.PinVerification.startFlow(view, Dashboard.class, "LOGIN");
}

Reset PIN functionality is an update that is available starting from version 0.4.5

🎉 You're done!

in the Dashboard

in your Main Activity

: PIN is recommended as a fallback method

before a transaction

Check the latest version here .

You need to set allowed methods for authenticating your users. To allow PIN and BIOMETRIC, go to

Check out for full Description

Check out for full Description

Call Cotter's to send the pin reset code

📘
https://github.com/cotterapp/android-sdk/releases
https://dev.cotter.app/rules
Reset PIN API
Import Cotter as a dependency
Set allowed Authentication Methods
Create a User
Initialize Cotter
Enroll Biometrics and PIN
Verify Biometrics
Contact us in Slack
Create a User API Reference
Get User API Reference
PIN and Biometric using Cotter's Android SDK
Set both Biometric and PIN to be allowed
PinEnrollment Flow