During Email/Phone Verification

Cotter's email/phone number verification is generally used to check if the email or phone number is active. For websites with no companion app, it is also used as the main method of login.

Cotter can return OAuth tokens when the user's email/phone numbers are verified, and the authentication_method will be set as OTP.

React Native SDK

In the React Native SDK, you would follow this guide to open Cotter's verification module. When the user's email or phone number is successfully verified, you'll receive information about the user and a signature from Cotter.

To also receive OAuth Tokens, modify your code by adding getOAuthToken = true in the parameters:

import { Verify } from 'react-native-cotter';

class Register extends PureComponent {
  ...
  openCotterAuth = async () => {
    var verify = new Verify(
      'https://js.cotter.app/app',   
      'https://www.cotter.app/api/v0',
      'myexample://auth_callback',
      API_KEY_ID,
      this.onError,
      this.onSuccess,  
      (getOAuthToken = true), // 👈 Add this parameter
    );
    await verify.openAuth('EMAIL');
  };
  ...
}

The response OnSuccess will be:

{
  "identifier": {
    "ID": "2ddc26f6-f392-4d7e-8607-1f57d41da045",
    "created_at": "2020-04-05T04:50:55.931771Z",
    "deleted_at": null,
    "device_name": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1 Mobile/15E148 Safari/604.1",
    "device_type": "BROWSER",
    "expiry": "2020-05-07T03:34:58.729745Z",
    "identifier": "[e-mail]",
    "identifier_type": "EMAIL",
    "public_key": "FvozWVGHo9lWE5ilLOF...",
    "timestamp": "2020-04-07T03:34:58.729745Z",
    "update_at": "2020-04-07T03:34:58.733779Z"
  },
  "token": { // You can ignore this if you're using the oauth_token 
    "expire_at": "1588822498",
    "identifier": "[e-mail]",
    "identifier_id": "2ddc26f6-f392-4d7e-8607-1f57d41da045",
    "identifier_type": "EMAIL",
    "receiver": "<your API KEY ID>",
    "signature": "XIbztHLKQSqzbnuBgyC+GfAK...",
    "timestamp": "1586230498"
  },
  "oauth_token": {  // 👈 NEW OAuth Tokens 👈
    "access_token": "eyJhbGciOiJFUz...",
    "auth_method": "OTP",
    "expires_in": 3600,
    "id_token": "eyJhbGciOiJFUz...",
    "refresh_token": "94:qv2SAJN5u2u...",
    "token_type": "Bearer"
  }
}

Cotter's React Native SDK automatically store your tokens securely inside the device's secure storage.

API for Mobile Apps

Using the API for Mobile Apps, you would follow this guide to get the identity of the user. When the user's email or phone number is successfully verified, you'll receive information about the user and a signature from Cotter.

To also receive OAuth Tokens, add a query parameter oauth_token=true in the http request:

https://www.cotter.app/api/v0/verify/get_identity?oauth_token=true

The full request would be:

curl -XPOST \
-H 'Content-type: application/json' \
-H 'API_KEY_ID: <api_key_id>' \
-d '{
  "code_verifier": "<code_verifier>",
  "authorization_code": "<authorization_code>",
  "challenge_id": <challenge_id>,
  "redirect_url": "<redirect_url>"
}' 'https://www.cotter.app/api/v0/verify/get_identity?oauth_token=true'

You'll get the following response:

JSON Response

{
  "identifier": {
    "ID": "2ddc26f6-f392-4d7e-8607-1f57d41da045",
    "created_at": "2020-04-05T04:50:55.931771Z",
    "deleted_at": null,
    "device_name": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1 Mobile/15E148 Safari/604.1",
    "device_type": "BROWSER",
    "expiry": "2020-05-07T03:34:58.729745Z",
    "identifier": "[e-mail]",
    "identifier_type": "EMAIL",
    "public_key": "FvozWVGHo9lWE5ilLOF...",
    "timestamp": "2020-04-07T03:34:58.729745Z",
    "update_at": "2020-04-07T03:34:58.733779Z"
  },
  "token": { // You can ignore this if you're using the oauth_token 
    "expire_at": "1588822498",
    "identifier": "[e-mail]",
    "identifier_id": "2ddc26f6-f392-4d7e-8607-1f57d41da045",
    "identifier_type": "EMAIL",
    "receiver": "<your API KEY ID>",
    "signature": "XIbztHLKQSqzbnuBgyC+GfAK...",
    "timestamp": "1586230498"
  },
  "oauth_token": {  // 👈 NEW OAuth Tokens 👈
    "access_token": "eyJhbGciOiJFUz...",
    "auth_method": "OTP",
    "expires_in": 3600,
    "id_token": "eyJhbGciOiJFUz...",
    "refresh_token": "94:qv2SAJN5u2u...",
    "token_type": "Bearer"
  }
}

Other SDKs (coming soon)

We'll add support for JS, Android and iOS soon 😉. Stay tuned!

Tokens must be stored securely within your application Use Android Keystore for Android and iOS KeyChain for iOS apps.

Getting and Removing tokens from the Storage

You need to pass the access_token to your backend server on every API calls. You also need to remove the tokens from storage to log out your users. Check out how to do that here:

Storing and Removing Tokens

Renewing Expired Tokens

Access tokens and ID tokens expires in 1 hour. When they're expired, you need to use the refresh_token to get new tokens. Check out how to renew expired tokens:

Renewing Expired Tokens