Sign In with Device

Our Android SDK offers the easiest way to integrate "Sign in with device" to your android app. You can simply call a function and it does most of the heavy lifting and authentication for you.

Concepts: Learn about how Sign in with Device works.
There are major updates planned for this feature. Contact us in Slack so we can help you prepare for it.
Overview
Authenticating users using Trusted Devices with Cotter's Android SDK consists of the following steps:
1.Import and Initialize Cotter
2.Sign up a new user and trust the current device
3.Sign in existing user from a Trusted and a Non-Trusted Device
What you're building
Trusted Devices on Cotter's Android SDK
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.4.0'
}
Check the latest version here https://github.com/cotterapp/android-sdk/releases. Then sync your gradle files.
Step 2: Initialize Cotter
You can now use the SDK to sign up a new user and setup the device as trusted, or sign in an existing user using the trusted device
In your MainActivity, initialize Cotter with your API_KEY_ID. You can get it from the Dashboard.
Cotter.init(
    this.getApplicationContext(),
    "<API_KEY_ID>",
);
Example:
MainActivity.java
public class MainActivity extends AppCompatActivity {
​
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
​
        Cotter.init(
            this.getApplicationContext(),
            "<API_KEY_ID>",
        );
    }
    ...
Step 3: Sign Up a New User and Register This Device as Trusted
1.The user should enter an identifier (an email, phone number, or username).
2.The SDK will register a new user with that identifier, and then enroll the current device as a Trusted Device.
Java
JSON result
Cotter.signUpWithDevice(this, userEmail, new Callback() {
    @Override
    public void onSuccess(JSONObject result) {
        Toast.makeText(getApplicationContext(), result.toString(), Toast.LENGTH_SHORT).show();
        Log.e("Success Register Device", result.toString() );
    }
​
    @Override
    public void onError(String error) {
        Toast.makeText(getApplicationContext(), error, Toast.LENGTH_SHORT).show();
    }
});
{
  "ID": "abcdefgh-abcd-abcd-abcd-571d2e2772c7", // Cotter User ID
  "client_user_id": "abcdefgh-abcd-abcd-abcd-571d2e2772c7",
  "created_at": "2020-07-23T23:29:21.85269Z",
  "default_method": "TRUSTED_DEVICE",
  "deleted_at": "0001-01-01T00:00:00Z",
  "enrolled": [
    "TRUSTED_DEVICE"
  ],
  "identifier": "[email protected]",
  "identifiers": null,
  "issuer": "YOUR_API_KEY_ID", // this is your API Key ID
  "oauth_token": {
    "access_token": "eyJhbGciO...",
    "id_token": "eyJhbGciOiJFU...",
    "refresh_token": "3:LGOY0pIVof6LgkWo...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "auth_method": "TRUSTED_DEVICE"
  },
  "updated_at": "2020-07-23T23:29:22.090131709Z"
}
This method is only for the first Trusted Device. You will get an error if you attempt to enroll another Trusted Device using enrollDevice when there's already a Trusted Device for the account. To enroll other devices, see Add a new Trusted Device.
Step 4: Authenticate from a Trusted Device
To authenticate a device, call the Cotter.signInWithDevice function. This will automatically detect whether the current device is a Trusted Device or not.
Java
Cotter.signInWithDevice(this, userEmail, this, Dashboard.class, new Callback() {
    @Override
    public void onSuccess(JSONObject result) {
        Toast.makeText(getApplicationContext(), result.toString(), Toast.LENGTH_SHORT).show();
        Log.e("Success logging in", result.toString() );
    }
​
    @Override
    public void onError(String error) {
        Toast.makeText(getApplicationContext(), error, Toast.LENGTH_SHORT).show();
    }
});
Parameters
signInWithDevice(Context ctx, String identifier, AppCompatActivity act, Class callbackClass, Callback callback)
identifier: Your user's identifier (email/phone/username) that was used to register this user in Step 3.
callbackClass : The next activity class that you want to redirect to when the authentication request is finished
callback : A custom Callback function that implements 2 methods: onSuccess and onError.
When an Authentication Event is requested using method TRUSTED_DEVICE, there are 2 possible cases:
Case 1: The current device is a Trusted Device
If the current device is a Trusted Device, it should automatically be approved, and you will receive a JSON result containing the requested Event and whether or not it's approved. The approval is based on whether or not the signature included in the request from the SDK is valid.
{
  ...
  "method": "TRUSTED_DEVICE",
  "new": false, // Is this a new pending event (should be false).
  "approved": true, // Is this event approved (should be true).
  
  "oauth_token": {
    "access_token": "eyJhbGciOiJFUz...", // validate this access token
    "id_token": "eyJhbGciOiJFUz...",
    "refresh_token": "5:cYIfabtspE1cBeD7KP...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "auth_method": "TRUSTED_DEVICE"
  }
}
​
You should see a result that the event is not new, and that it's approved. This is because the signature from the Trusted Device is sufficient to prove that the device is authorized.
When passing this Response to your backend, you need to check if this JSON is valid and if it comes from Cotter's server by validating the access token.
Checkout how to verify the OAuth Tokens from Cotter here:
Verifying JWT Tokens
Case 2: The current device is NOT a Trusted Device
We'll cover this in the next guide:
Authenticate from a Non-Trusted Device
🎉 You're done!
Next Steps
Authenticate from a Non-Trusted Device
Add a new Trusted Device
Customization

SDK Reference - Previous

Android

Authenticate from a Non-Trusted Device

Last modified 1yr ago

Copy link

Outline

Overview

What you're building

Step 1: Import Cotter as a dependency

Step 2: Initialize Cotter

Step 3: Sign Up a New User and Register This Device as Trusted

Step 4: Authenticate from a Trusted Device

🎉 You're done!

Next Steps