# Getting Started Get started quickly using Cotter's SDK to integrate passwordless login and email/phone number verification into your websites and apps ## Get Started Cotter allows you to build a login system in just a few minutes. **There are 3 main methods of logging-in.** You can either choose 1 or combine the methods. Quickly get started with **our 5-minutes tutorials**: πŸ’¬ **Sign in with email/phone number:** Authenticate using a Magic Link or Verification Code. [Learn More β†’](/features/verify-email-phone) * [HTML Quickstart](/quickstart-guides/html-magic-link-with-email-and-phone) * [React Quickstart](/quickstart-guides/react-magic-link-with-email-and-phone) * [Next.js Tutorial](https://blog.cotter.app/passwordless-login-with-email-and-json-web-token-jwt-authentication-with-nextjs/) * [Angular Tutorial](https://blog.cotter.app/angular-send-email-sms-and-whatsapp-verification-code-for-new-users-worldwide/) * [Webflow Tutorial](https://blog.cotter.app/integrate-cotter-magic-link-to-webflow-in-less-than-15-minutes/) πŸ” **Sign In with Device on Mobile Apps:** Authenticate users based on the ownership of a device. [Learn More β†’](/features/passwordless-login) * [React Native Quickstart](/quickstart-guides/react-native-quickstart) * [Flutter Quickstart](/quickstart-guides/flutter-sign-in-with-device) * [iOS Quickstart](/quickstart-guides/ios-quickstart) 🧬 **Sign in with WebAuthn:** Authenticate users using TouchID/Windows Hello from your website. [Learn More β†’](/features/sign-in-with-webauthn) * [React Quickstart](/quickstart-guides/react-webauthn) ## Customization Customize Cotter's Login Form from the [Dashboard > Branding](https://dev.cotter.app/). Currently this works for the Web SDKs for Sign in with Email/Phone using a Magic Link and OTP. ## Dig Deeper Follow the full SDK reference for a fully customizable login flow and get OAuth 2.0 support for your API endpoints. * [Web](/sdk-reference/web) * [React Native](/sdk-reference/react-native) * [Flutter](/sdk-reference/flutter) * [iOS](/sdk-reference/ios) * [Android](/sdk-reference/android) * [Other Mobile App Frameworks](/sdk-reference/api-for-other-mobile-apps) * [Backend: Handling Response](/sdk-reference/backend-handling-response) that you receive when a user authenticates ## OAuth 2.0: Get Access Token from Cotter Cotter can generate OAuth Tokens (access token, id token, and refresh token) to be used for your APIs. This functionality is available from Cotter's SDK. {% content-ref url="/pages/-M4HUyscnpVWv0mVDRba" %} [πŸ—οΈ Getting Access Token](/getting-access-token/handling-authentication-with-cotter) {% endcontent-ref %} ## Example Apps [HTML Example](https://codesandbox.io/s/client-side-working-example-hiy8w?file=/index.html) [ReactNative Example App](https://github.com/cotterapp/react-native-sdk/tree/master/examples) [Flutter Example App](https://github.com/cotterapp/flutter-sdk/tree/master/example) [Android Example App](https://github.com/cotterapp/android-example) [Biometric and PIN iOS Example](https://github.com/cotterapp/ios-sdk) # Features & Concepts There are several steps and features that makes Cotter a powerful authentication service for you. To use the most out of Cotter, you can combine the 3 features that we offer: **Sign in with Device**, **Sign in with Email/Phone Number**, and **WebAuthn (Biometrics for websites).** ## 1. Sign in with Device with an In-App Prompt Trusted devices works like DUO or Apple's Trusted Devices. Basically, we turn your mobile device into a security key such that your account is only accessible from the devices that you trust. We create a cryptographic key pair and store it in your device's secure storage. We'll then use cryptographic functions to check the requests produced by the key in your device to authenticate account access. Learn more at [FIDO](https://fidoalliance.org/how-fido-works/). Trusted devices are available for mobile apps, and websites with an accompanying mobile app. If your website doesn't have a mobile app and you want to utilize this functionality, your users can download the Cotter app instead (coming soon). {% content-ref url="/pages/-M14UhiTa9EBe1jIQi4Y" %} [Sign In with Device](/features/passwordless-login) {% endcontent-ref %} ## 2. **Sign in with Email or Phone Number with Magic Link or OTP** Cotter works as a universal single-sign-on for all websites and apps that integrates Cotter. Users who have verified their email or phone number once in any of the participating apps will not need to re-verify email & phone number. > Your users don't need to be redirected to Cotter's website, or even know that Cotter exists. You can embed Cotter inside your website and app. {% content-ref url="/pages/-M0QHRAfzQweYx\_DczkH" %} [Sign In with Email/Phone Number](/features/verify-email-phone) {% endcontent-ref %} ## 3. WebAuthn WebAuthn allows websites to authenticate users using TouchID or Windows Hello from the browser. This feature makes it faster for your users to login. Users can set up their current device to allow login with WebAuthn, and the user will be prompted to use TouchID or Windows Hello on subsequent logins. {% content-ref url="/pages/-MDcc97fCNNgjEv4ihN4" %} [Sign In with WebAuthn](/features/sign-in-with-webauthn) {% endcontent-ref %} # Sign In with Email/Phone Number Sign in faster using a magic link or OTP sent to users via email, SMS, or WhatsApp. ## How it works Users can authenticate using just their email or phone number. On their first time using Cotter, they will be prompted to enter a verification code or press a magic link {% hint style="success" %} On subsequent authentication requests through any website, they will be able to **instantly get verified without needing a verification code.** {% endhint %} ## First Ever Sign Up On their first ever signup to a website/app that uses Cotter, the user have to enter a verification code. ![First ever signup to a website/app that uses Cotter](/files/-M9M-J5jm5GYC1L6z5P6) #### 1. The user enter their email or phone number #### 2. They will receive a verification code or magic link to their email or phone number. The user will then enter the verification code or press the magic link #### 3. We will return a response in the callback function with the user's email or phone number and a JWT token to verify that the user is authenticated. {% hint style="success" %} **✨At this point, we tie the user's browser or device with their email / phone number.** When the user then sign up to another website that uses Cotter, the user **don't need to re-verify their email or phone number.** Instead, our website or SDK will check if we recognize the device with the credentials, and will automatically go to step 3 above. {% endhint %} ## Subsequent Logins After the first signup, anytime the user need to sign-up or login to **any website or app that uses Cotter**, the user just needs to enter the email or phone number they want to use, and they'll be **instantly verified**. ![On subsequent logins, the user don't need to enter verification code](/files/-M9M0Ho0FN1zEdY-5_0K) #### 1. The user enter their email or phone number #### 2. The user is already verified, and can continue their registration or login :tada: {% hint style="info" %} Currently our sessions lasts for 30 days. After 30 days, the user have to re-enter a verification code. In the near future, we will allow you to check **the last login timestamp** and **decide** whether you'd like to **send another verification code or not**. {% endhint %} ## Quickstarts {% content-ref url="/pages/-M4bSYVl2B09-3932YAm" %} [Broken mention](broken://pages/-M4bSYVl2B09-3932YAm) {% endcontent-ref %} ## Guides #### Web {% content-ref url="/pages/-M0ROJn7tosL9qeumqFd" %} [Sign In with Email/Phone Number](/sdk-reference/web/web-sdk-verify-email-phone) {% endcontent-ref %} #### React Native {% content-ref url="/pages/-M1dk\_Rosjlkj52Hq\_6R" %} [Sign In with Email/Phone Number](/sdk-reference/react-native/react-native-sdk-verify-email-phone) {% endcontent-ref %} #### iOS {% content-ref url="/pages/-M35aUobglanfiWqjf7S" %} [Sign In with Email/Phone Number](/sdk-reference/ios/ios-sdk-verify-email-phone) {% endcontent-ref %} #### Android {% content-ref url="/pages/-M0et2D8qa-mVoDh-tjp" %} [Sign In with Email/Phone Number](/sdk-reference/android/android-sdk-1) {% endcontent-ref %} #### Other Mobile Apps {% content-ref url="/pages/-M0QVaCMLRWd0jUsIcYn" %} [Verify Email/Phone Number](/sdk-reference/api-for-other-mobile-apps/api-for-mobile-apps) {% endcontent-ref %} # Sign In with Device Sign in faster with a prompt sent to your mobile app. ## What is a Trusted Device? ![Cotter's Trusted Device SDK](/files/-M14Xwy2Vq-ECRII3PXW) A Trusted Device is a mobile device that you trust, where you can access your account without needing a password. When you try to access your account from a Non-Trusted Device, it will require an approval from the app installed in the Trusted Device. Usually, your first Trusted Device will be the mobile phone you used to register to an app. You can then add other devices to be a Trusted Device for your account. ## How it's Secure ![How It Works](/files/-M85aPVXclped6ySpTsB) Cotter's SDK follows the [FIDO Protocol](https://fidoalliance.org/how-fido-works/) to implement Trusted Devices. The way it works is that Cotter's SDK will generate cryptographic key pair that replaces your password. This key will be stored securely in your device. Because of this, your device is called a Trusted Device, because your device is the only one who knows this keys. Because of the way asymmetric cryptography works, your secret key is never sent over the internet to any server, not even Cotter's server. We only need to verify that requests are actually made with the key using cryptographic functions, to ensure that it is actually coming from your Trusted Device. ## Quickstarts {% content-ref url="/pages/-M6Eb1vLZRs1\_0ZAMKrR" %} [React Native – Sign in with Device](/quickstart-guides/react-native-quickstart) {% endcontent-ref %} {% content-ref url="/pages/-M6EaO2M9ot00du8W\_bR" %} [iOS – Sign in with Device](/quickstart-guides/ios-quickstart) {% endcontent-ref %} {% content-ref url="/pages/-M9aaGUmTZYju\_sjd17x" %} [Flutter – Sign in with Device](/quickstart-guides/flutter-sign-in-with-device) {% endcontent-ref %} ## Guides #### React Native {% content-ref url="/pages/-M2kTuM6W90CT9IpIxHq" %} [Sign In with Device](/sdk-reference/react-native/react-native-sdk-passwordless-login) {% endcontent-ref %} #### Flutter {% content-ref url="/pages/-M9angupK73fWUZjM7fe" %} [Sign In with Device](/sdk-reference/flutter/sign-in-with-device) {% endcontent-ref %} #### iOS {% content-ref url="/pages/-M4q-LjGBIcIq3PgnYt6" %} [Sign In with Device](/sdk-reference/ios/ios-sdk-passwordless-login) {% endcontent-ref %} #### Android {% content-ref url="/pages/-M14g3WtD4o3ZG9N2j9G" %} [Sign In with Device](/sdk-reference/android/older-sdk-version/android-sdk) {% endcontent-ref %} # How it works There are several different cases for user registration and login, and we're going to cover them all: ### Registration ![Registration with Cotter's Trusted Device](/files/-MEjHpcQLCKgGtxbn6XJ) When a user registers to your app, you can immediately call Cotter's SDK to register the mobile device as a Trusted Device. This way, the user's account can now be accessed from the trusted device without needing a password. ### Login from a Trusted Device ![Logging-in from a Trusted Device](/files/-MEjHwvrecyViDUP48sd) Logging in from a trusted device is instant. Your users can immediately access their account without doing anything. Your app can optionally require Biometric/PIN to make it more secure. ### Login from a Non-Trusted Device ![Login from a Non-Trusted Device](/files/-MEjI28l_lHOpx2OlPl6) If your user try to login from a different phone, or from a web browser, then they will receive a prompt in their Trusted Device, asking them to approve the login request. Once approved, the user can access their account from Non-Trusted Device. **But this doesn't mean that the new device is now a trusted device.** Subsequent logins from a Non-Trusted Device will **always** require approval, even when approved. ### Registering a New Device as a Trusted Device ![Adding a New Trusted Device](/files/-MEjInS_0JWSfygUjI2v) The user can register another device as an additional Trusted Device. The Trusted Device will need to scan a QR Code shown in the other device to explicitly register that other device as a Trusted Device. Once the new device is registered as a Trusted Device, the user can now access their account from both devices with ease. ## Quickstarts {% content-ref url="/pages/-M6Eb1vLZRs1\_0ZAMKrR" %} [React Native – Sign in with Device](/quickstart-guides/react-native-quickstart) {% endcontent-ref %} {% content-ref url="/pages/-M9aaGUmTZYju\_sjd17x" %} [Flutter – Sign in with Device](/quickstart-guides/flutter-sign-in-with-device) {% endcontent-ref %} {% content-ref url="/pages/-M6EaO2M9ot00du8W\_bR" %} [iOS – Sign in with Device](/quickstart-guides/ios-quickstart) {% endcontent-ref %} ## SDK Reference #### React Native {% content-ref url="/pages/-M2kTuM6W90CT9IpIxHq" %} [Sign In with Device](/sdk-reference/react-native/react-native-sdk-passwordless-login) {% endcontent-ref %} #### Flutter {% content-ref url="/pages/-M9angupK73fWUZjM7fe" %} [Sign In with Device](/sdk-reference/flutter/sign-in-with-device) {% endcontent-ref %} **iOS** {% content-ref url="/pages/-M4q-LjGBIcIq3PgnYt6" %} [Sign In with Device](/sdk-reference/ios/ios-sdk-passwordless-login) {% endcontent-ref %} #### Android {% content-ref url="/pages/-MCxyo3ix-jqWDQysF0g" %} [Sign In with Device](/sdk-reference/android/sign-in-with-device) {% endcontent-ref %} # Sign In with WebAuthn WebAuthn allows users to authenticate with their device's authenticator, like TouchID or Windows Hello, to websites via their browsers. ![](/files/-MCkItqjAs5Z18uMfGn-) Because WebAuthn is not supported on all browsers yet, **the WebAuthn feature always have a fallback method to Magic Link or OTP verification.** ### Signing Up ![](/files/-MEjNFATmbGxrmg0Ndmb) When the user first sign up for your website, they don't have a WebAuthn credential set up. The user will first enter their **email** or **phone number:** * **Step 1:** Verify the user's email or phone number using OTP or Magic Link * **Step 2:** The SDK will automatically prompt the user to set up WebAuthn for this device. * **Step 3:** If the user agrees and touch the TouchID sensor, the user can subsequently login using TouchID from the current laptop. ### **Logging In** ![](/files/-MEjO9pP2Gmnu_xbj73G) The user may or may not have any WebAuthn credentials set up: * **Step 1:** The user enters their email or phone number * **Step 2:** The SDK checks if the user have any WebAuthn credential set up * **Yes, the user have a WebAuthn Credential**: The SDK will automatically ask the user to login using WebAuthn. The user have the option to fallback to use Magic Link or OTP * **No, the user never setup WebAuthn before:** The SDK will continue authenticating the user using Magic Link or OTP, then ask the user to setup WebAuthn on the current laptop. # All Guides & Tutorials Quickly get started with **our 5-minutes tutorials**: πŸ’¬ **Sign in with email/phone number:** Authenticate using a Magic Link or Verification Code. [Learn More β†’](/features/verify-email-phone) * [HTML Quickstart](/quickstart-guides/html-magic-link-with-email-and-phone) * [React Quickstart](/quickstart-guides/react-magic-link-with-email-and-phone) * [Next.js Tutorial](https://blog.cotter.app/passwordless-login-with-email-and-json-web-token-jwt-authentication-with-nextjs/) * [Angular Tutorial](https://blog.cotter.app/angular-send-email-sms-and-whatsapp-verification-code-for-new-users-worldwide/) * [Webflow Tutorial](https://blog.cotter.app/integrate-cotter-magic-link-to-webflow-in-less-than-15-minutes/) πŸ” **Sign In with Device on Mobile Apps:** Authenticate users based on the ownership of a device. [Learn More β†’](/features/passwordless-login) * [React Native Quickstart](/quickstart-guides/react-native-quickstart) * [Flutter Quickstart](/quickstart-guides/flutter-sign-in-with-device) * [iOS Quickstart](/quickstart-guides/ios-quickstart) 🧬 **Sign in with WebAuthn:** Authenticate users using TouchID/Windows Hello from your website. [Learn More β†’](/features/sign-in-with-webauthn) * [React Quickstart](/quickstart-guides/react-webauthn) # HTML – Sign in with Email/Phone Easily add email and phone number verification using Cotter's SDK. Send a magic link to your users via email, SMS or WhatsApp in just a few lines of code. Cotter's Magic Link authenticates your user using a link. It allows seamless, fast, and secure way for your user to login to your Web App. Follow this simple guide to see how it works! {% embed url="" %} ### Step 0: Get the template code To follow this guide, let's use our [Hello World Template](https://codesandbox.io/s/client-side-template-prf4d) in CodeSandbox! ### Step 1: Import Cotter as a dependency Copy the following script to the head section of your HTML page ```markup ``` ### Step 2: Setup a `div` with id `cotter-form-container` element to contain cotter's form ```markup
``` Please note that id has to be `cotter-form-container` for the form to show up. ### Step 3: Initialize Cotter > You need your API\_KEY\_ID for this step. Create a developer account and create a Project to get your API keys. The API Keys will only be shown once! Grab your `API_KEY_ID` from the dashboard, then replace `` with your `API_KEY_ID`. ```markup ``` > πŸŽ‰ You're done! Now that you know how it works on the client side, let's check out how to process Cotter's payload in your backend so you can start registering and logging in users in your backend server. Here's a [fully working example](https://codesandbox.io/s/magic-link-working-example-c5j7f) of the guide we went over. {% hint style="info" %} To send code/link via SMS or WhatsApp, you'll need to add some balance to you project in the [Dashboard](https://dev.cotter.app/). {% endhint %} ## πŸ‘‰ What's Next? ### Customize the Form You can customize the form from the [Dashboard](https://dev.cotter.app/) > Branding. You can also [add Custom CSS](/sdk-reference/web/web-sdk-verify-email-phone/styling#adding-your-own-css). ### Add Additional Fields [**Add Additional Fields**](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#additional-fields) like Name, Address, etc to the login form. ### **Register User to your Backend** When the user successfully authenticated, send Cotter's response to your backend to either create a new user or log the user in. Learn how to send Cotter's response and verify it in your backend: {% content-ref url="/pages/-MDcFwnPyQzT3MiP1tHe" %} [Backend: Handling Response](/sdk-reference/backend-handling-response) {% endcontent-ref %} # React – Sign in with Email/Phone Easily add email and phone number verification using Cotter's SDK. Send a magic link to your users via email, SMS or WhatsApp in just a few lines of code. Cotter's Magic Link authenticates your user using a link. It allows seamless, fast, and secure way for your user to login to your Web App. Follow this simple guide to see how it works! ![Add Magic Link Authentication in just a few minutes](/files/-MBrfjtocuzcysGXyr38) ### Step 1: Import Cotter as a dependency ``` yarn add cotter ``` ### Step 2: Initialize Cotter and Show the Form ```javascript import React, { useEffect, useState } from "react"; import Cotter from "cotter"; // 1️⃣ Import Cotter function App() { const [payload, setpayload] = useState(null); // 2️⃣ Initialize and show the form useEffect(() => { var cotter = new Cotter(API_KEY_ID); // πŸ‘ˆ Specify your API KEY ID here cotter .withFormID("form_default") // Use customization for form "form_default" .signInWithLink() // use .signInWithOTP() to send an OTP .showEmailForm() // use .showPhoneForm() to send magic link to a phone number .then(response => { setpayload(response); // show the response in our state }) .catch(err => console.log(err)); }, []); return (
{/* 3️⃣ Put a
that will contain the form */} 
{JSON.stringify(payload, null, 4)}
); } export default App; ``` [Create a free account and go to the dashboard](https://dev.cotter.app/) to get your `API_KEY_ID` . 1. Import Cotter 2. Call `signInWithLink` to use Magic Link or `signInWithOTP` to use OTP, followed by `showEmailForm` or `showPhoneForm`, and get the response as a promise. 3. Setup a `
` with `id="cotter-form-container"` that will contain the form. {% hint style="info" %} To send code/link via SMS or WhatsApp, you'll need to add some balance to you project in the [Dashboard](https://dev.cotter.app/). {% endhint %} ### πŸŽ‰ **You're done!** Here's a [working example of the React app that we just made](https://codesandbox.io/s/react-magic-link-complete-90vig?file=/src/App.js). ## ✏️ **Ready to setup & customize your login?** ### **Customize the Form** Easily customize the form from [Cotter's Dashboard](https://dev.cotter.app/) > Branding. ### **Full JS SDK Reference** {% content-ref url="/pages/-M0ROJn7tosL9qeumqFd" %} [Sign In with Email/Phone Number](/sdk-reference/web/web-sdk-verify-email-phone) {% endcontent-ref %} ## πŸ‘‰ What's Next? ### Customize the Form You can customize the form from the [Dashboard](https://dev.cotter.app/) > Branding. You can also [add Custom CSS](/sdk-reference/web/web-sdk-verify-email-phone/styling#adding-your-own-css). ### Add Additional Fields [**Add Additional Fields**](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#additional-fields) like Name, Address, etc to the login form. ### **Register User to your Backend** When the user successfully authenticated, send Cotter's response to your backend to either create a new user or log the user in. Learn how to send Cotter's response and verify it in your backend: {% content-ref url="/pages/-MDcFwnPyQzT3MiP1tHe" %} [Backend: Handling Response](/sdk-reference/backend-handling-response) {% endcontent-ref %} # React – WebAuthn Sign in users faster using WebAuthn: sign in with TouchID or Windows Hello from a web browser. Cotter's WebAuthn authenticates your user using either TouchID or Windows Hello **from their browser**. This means it works **from your website.** It allows seamless, fast, and secure way for your user to login to your Web App. Follow this simple guide to see how it works! ![WebAuthn with Cotter's JS SDK](/files/-MCkItqjAs5Z18uMfGn-) {% hint style="success" %} [**Try it live**](https://cotter.herokuapp.com/) **on our Example Next.js Project.** Check out the complete code on [Github](https://github.com/cotter-code/guide-next-webauthn). {% endhint %} ### Step 1: Import Cotter as a dependency ``` yarn add cotter ``` *(This feature is available on version >= 0.3.4)* ### Step 2: Initialize Cotter and Show the Form ```javascript import React, { useEffect, useState } from "react"; import Cotter from "cotter"; // 1️⃣ Import Cotter function App() { const [payload, setpayload] = useState(null); // 2️⃣ Initialize and show the form useEffect(() => { var cotter = new Cotter(API_KEY_ID); // πŸ‘ˆ Specify your API KEY ID here cotter .withFormID("form_default") // Use customization for form "form_default" .signInWithWebAuthnOrLink() .showEmailForm() .then(response => { setpayload(response); // show the response in our state }) .catch(err => console.log(err)); }, []); return (
{/* 3️⃣ Put a
that will contain the form */} 
{JSON.stringify(payload, null, 4)}
); } export default App; ``` ​[Create a free account and go to the dashboard](https://dev.cotter.app/) to get your `API_KEY_ID` . 1. Import Cotter 2. Call `signInWithWebAuthnOrLink` to use WebAuthn with fallback Magic Link, followed by `showEmailForm` or `showPhoneForm`, and get the response as a promise. 3. Setup a `
` with `id="cotter-form-container"` that will contain the form. ### πŸŽ‰ **You're done!** ## ✏️ **Ready to setup & customize your login?** ### **Customize the Form** Easily customize the form from [Cotter's Dashboard](https://dev.cotter.app/) > Branding. ### **Full JS SDK Reference** {% content-ref url="/pages/-MCk3X5Dh4Fkxp20D4Rt" %} [Sign In with WebAuthn](/sdk-reference/web/sign-in-with-webauthn) {% endcontent-ref %} ## πŸ‘‰ What's Next? ### Customize the Form You can customize the form from the [Dashboard](https://dev.cotter.app/) > Branding. You can also [add Custom CSS](/sdk-reference/web/web-sdk-verify-email-phone/styling#adding-your-own-css). ### Add Additional Fields [**Add Additional Fields**](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#additional-fields) like Name, Address, etc to the login form. ### **Register User to your Backend** When the user successfully authenticated, send Cotter's response to your backend to either create a new user or log the user in. Learn how to send Cotter's response and verify it in your backend: {% content-ref url="/pages/-MDcFwnPyQzT3MiP1tHe" %} [Backend: Handling Response](/sdk-reference/backend-handling-response) {% endcontent-ref %} # React Native – Sign in with Device Cotter's Passwordless SDK authenticates your user based on their device. It allows a seamless, fast, and secure way for your user to login to your React Native App. ## Sign in with Device In this guide we'll allow users to **Sign In with Device** using Cotter's SDK. {% hint style="info" %} Make sure you're using `react-native` version **< 0.63** {% endhint %} ### Step 1️: Get Cotter SDK **Head to** [**https://dev.cotter.app/rules**](https://dev.cotter.app/rules) **and allow Trusted Devices in the dashboard.** {% tabs %} {% tab title="yarn" %} ``` yarn add react-native-cotter react-native-device-info rn-secure-storage react-native-randombytes react-native-camera react-native-svg react-native-securerandom buffer react-native-inappbrowser-reborn react-native-sha256 npx pod-install ios ``` {% endtab %} {% tab title="npm" %} ``` npm install --save react-native-cotter react-native-device-info rn-secure-storage react-native-randombytes react-native-camera react-native-svg react-native-securerandom buffer react-native-inappbrowser-reborn react-native-sha256 npx pod-install ios ``` {% endtab %} {% endtabs %} **Make sure you use version >= 0.2.0.** Checkout additional steps [for Android](https://docs.cotter.app/trusted-devices/react-native-sdk#for-android), [React Native < 0.60](https://docs.cotter.app/trusted-devices/react-native-sdk#using-react-native-less-than-0-60), and [Manual Installation](https://docs.cotter.app/trusted-devices/react-native-sdk#manual-installation). ### Step 2️: Wrap your root component with `connectCotterWrapper` ```javascript import {connectCotterWrapper} from 'react-native-cotter'; class MyApp extends Component {...} export default connectCotterWrapper(MyApp); ``` ### Step 3️: Register user and trust this device This method `signUpWithDevice` will register the user based on the user's `identifier` to Cotter and then trust the current device. {% tabs %} {% tab title="JavaScript" %} ```javascript import { Cotter } from "react-native-cotter"; const register = (identifier) => { // Signup the user and trust this device var cotter = new Cotter(API_KEY_ID); cotter.signUpWithDevice( identifier, // User's email, phone or username (response) => {console.log(response)}, // OnSuccess function (error) => {console.log(error)}, // OnError function ); }; ``` {% endtab %} {% tab title="Response" %} ```javascript // Returns the newly created User object in Cotter // along with oauth tokens { "ID": "cccccccc-cccc-cccc-cccc-cccccccccccc", "client_user_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "created_at": "2020-06-09T03:50:04.005779Z", "default_method": "TRUSTED_DEVICE", "deleted_at": null, "enrolled": [ "TRUSTED_DEVICE" ], "identifiers": [ "hello@cotter.app" ], "issuer": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "oauth_token": { "access_token": "eyJhbGciOi...", "auth_method": "TRUSTED_DEVICE", "expires_in": 3600, "id_token": "eyJhbGciOiJFU...", "refresh_token": "6177:MufdKMIk2XP...", "token_type": "Bearer" }, "update_at": "2020-06-09T03:50:04.77575278Z" } ``` {% endtab %} {% endtabs %} ### Step 4️: Logging In from a Trusted Device Use the `signInWithDevice` method to login with the same `identifier` as the one registered above. {% tabs %} {% tab title="JavaScript" %} ```javascript import { Cotter } from "react-native-cotter"; const login = (identifier) => { var cotter = new Cotter(API_KEY_ID); cotter.signInWithDevice( identifier, // User's email, phone or username (response) => {console.log(response)}, // OnSuccess function (error) => {console.log(error)}, // OnError function ); } ``` {% endtab %} {% tab title="Response" %} ```javascript { "ID": 1361, // Event ID "CreatedAt": "2020-02-27T22:22:48.705212512Z", "UpdatedAt": "2020-02-27T22:22:48.705212512Z", "DeletedAt": null, "client_user_id": "1014", // your client's User ID "issuer": "afcabd98-745f-4b9e-98de-af968d9951d3", // your API Key "event": "",// requested event (LOGIN, or TRANSACTION, etc) "ip": "192.168.232.2", "location": "Unknown", "timestamp": "1582842167", "method": "TRUSTED_DEVICE", // auth method: TRUSTED_DEVICE (other choices are PIN / BIOMETRIC) "new": false, // Is this a new pending event. More explanation below about Non-Trusted Device "approved": true, // Is this event approved. "signature": "oonMGCAxp3..." // Signature to make sure this event comes from Cotter's server } ``` {% endtab %} {% endtabs %} ## πŸŽ‰ You're Done ![](/files/-M7506mlkqL9gr-du1gI) Now you can allow your users to **Sign In with Device** with just 1 tap. When your sessions expires, you can also **Sign In User Silently** by just calling the method `signInWithDevice` above. #### Find a more detailed version of this guide in our Trusted Devices section {% content-ref url="/pages/-M2kTuM6W90CT9IpIxHq" %} [Sign In with Device](/sdk-reference/react-native/react-native-sdk-passwordless-login) {% endcontent-ref %} ## πŸ‘‰ What's Next? ### Verify User's Email or Phone Number {% content-ref url="/pages/-M1dk\_Rosjlkj52Hq\_6R" %} [Sign In with Email/Phone Number](/sdk-reference/react-native/react-native-sdk-verify-email-phone) {% endcontent-ref %} ### Logging-in from Another Device {% content-ref url="/pages/-M2pWufvpIxKQcm3t4RP" %} [Authenticate from a Non-Trusted Device](/sdk-reference/react-native/react-native-sdk-passwordless-login/authenticate-from-a-non-trusted-device) {% endcontent-ref %} # iOS – Sign in with Device Cotter's Passwordless SDK authenticates your user using the FIDO protocol. It allows a seamless, fast, and secure way for your user to login to your iOS App. Authenticate your users in 4 simple steps: ## Sign in with Device In this guide we'll allow users to **Sign In with Device** using Cotter's SDK. ### Step 1: Import Cotter as a dependency **Head to** [**https://dev.cotter.app/rules**](https://dev.cotter.app/rules) **and allow Trusted Devices in the dashboard.** We use Cocoapods as our SDK host. Add `pod 'Cotter'` to your podfile then run `pod install`. ### Step 2: Initialize Cotter In your app's `AppDelegate.swift`, initialize Cotter with your API keys. ```swift import Cotter // IMPORTANT: IMPORT COTTER AS DEPENDENCY ... func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { Cotter.configureWithLaunchOptions( launchOptions: launchOptions, apiSecretKey: , apiKeyID: ) } ``` ### Step 3: Register your user To register, simply call the following function anywhere in your app. Make sure you do `import Cotter` at the start of the swift file. ```swift Passwordless.shared.register( identifier: ) ``` ### Step 4: Logging in When a user logs in, call the following function in your view controller ```swift Passwordless.shared.parentVC = self Passwordless.shared.login( identifier: , cb: { (token: CotterOAuthToken?, err:Error?) in if err != nil { // case 1: handle error as necessary } if token == nil { // case 2: user is unauthorized } // case 3: user is authorized }) ``` Then you can handle 3 cases mentioned in the comments in any way you like. ## πŸ‘‰ Next steps That's it! You have successfully build a seamless, fast, and secure login mechanism with Cotter. #### Integrate Cotter's push notification services {% content-ref url="/pages/-MCiZep6L97mjBj93JTl" %} [Push Notification](/sdk-reference/ios/ios-sdk-passwordless-login/ios-push-notification) {% endcontent-ref %} #### Verify User's Email or Phone Number {% content-ref url="/pages/-M35aUobglanfiWqjf7S" %} [Sign In with Email/Phone Number](/sdk-reference/ios/ios-sdk-verify-email-phone) {% endcontent-ref %} # Flutter – Sign in with Device Cotter's Passwordless SDK authenticates your user based on their device. It allows a seamless, fast, and secure way for your user to login to your React Native App. ## Sign in with Device In this guide we'll allow users to **Sign In with Device** using Cotter's SDK. Add [Cotter's SDK](https://pub.dev/packages/cotter#-installing-tab-) to your `pubspec.yaml` , then run `flutter pub get`. You may need to restart your flutter for it to run pod install (stop flutter run and re run it). ```yaml dependencies: cotter: ``` **For Android**: Update `minSdkVersion` to `18` [following the installation instructions](/sdk-reference/flutter). Import Cotter in your `lib/main.dart`, then initialize it inside `HomePageState`. ```dart import 'package:cotter/cotter.dart'; // Import Cotter class HomePageState extends State { ... // 1⃣ Initialize Cotter Cotter cotter = new Cotter(apiKeyID: API_KEY_ID); // πŸ‘ˆ Specify your API KEY ID here // 2️⃣ Sign Up Function void signUp() async { try { // πŸš€ One-line Sign Up var user = await cotter.signUpWithDevice(identifier: inputController.text); } catch (e) { print(e) } } // 3️⃣ Login Function void login(BuildContext context) async { try { // πŸš€ One-line Login var event = await cotter.signInWithDevice(identifier: inputController.text, context: context); } catch (e) { print(e) } } @override Widget build(BuildContext context) { ... } } ``` You can [create a free account at Cotter](https://dev.cotter.app) to get your `API_KEY_ID`. **Sign Up:** Call `cotter.signUpWithDevice` and input the user's email, phone, or username. This will create a new user in Cotter and trust the current device to allow logins. This function returns a [User object](/api-reference/user-api/user-object). **Sign In:** Call `cotter.signInWithDevice` . If the user is logging-in [from a device that they trust](/features/passwordless-login), they'll automatically be approved. This function returns an [Event object](/api-reference/event-object). {% hint style="info" %} **Make sure you allow Trusted Devices Method in the** [**dashboard**](https://dev.cotter.app)**.** {% endhint %} ## πŸŽ‰ That's It! Simply call the `signUp` and `login` functions from your login page, and you can allow your users to **Sign In with Device** with just 1 tap**.** ![Passwordless Login with Flutter using Cotter's SDK](/files/-M9agBdGGVrDaZwCHkiO) ## What's Next? **1. Approve login requests from a non-trusted device** {% content-ref url="/pages/-M9arREAyqZyslAP96BY" %} [Authenticate from a Non-Trusted Device](/sdk-reference/flutter/sign-in-with-device/authenticate-from-a-non-trusted-device) {% endcontent-ref %} #### 2. Getting the Logged-in User {% content-ref url="/pages/-M9awQf5uqyq2X9ZO4JM" %} [Getting the Logged-in User](/sdk-reference/flutter/getting-the-logged-in-user) {% endcontent-ref %} #### 3. Getting Access Token, ID Token, and Refresh Token {% content-ref url="/pages/-M9axG8HPu6f\_at6wCcT" %} [Getting OAuth Tokens](/sdk-reference/flutter/getting-oauth-tokens) {% endcontent-ref %} # Web The easiest way to add Passwordless Login and Email/Phone Number Verification to your Websites. ## Complete Guides #### Sign in with Email/Phone Number Authenticate users by sending a Magic Link or OTP via email, SMS, or WhatsApp {% content-ref url="/pages/-M0ROJn7tosL9qeumqFd" %} [Sign In with Email/Phone Number](/sdk-reference/web/web-sdk-verify-email-phone) {% endcontent-ref %} #### Sign in with WebAuthn Authenticate users using TouchID or Windows Hello from your website. {% content-ref url="/pages/-MCk3X5Dh4Fkxp20D4Rt" %} [Sign In with WebAuthn](/sdk-reference/web/sign-in-with-webauthn) {% endcontent-ref %} #### Sign in with Device If you have **mobile app**, you can ask the user to approve the login request from their phone. {% content-ref url="/pages/-M3o-GTINgCweb4ATz-9" %} [Sign In with Device](/sdk-reference/web/web-sdk-passwordless-login) {% endcontent-ref %} ## Quickstart Guides {% content-ref url="/pages/-MBpqtdlR54h41rVFGWy" %} [React – Sign in with Email/Phone](/quickstart-guides/react-magic-link-with-email-and-phone) {% endcontent-ref %} {% content-ref url="/pages/-MAUbWpO8XONhF-vdxAG" %} [HTML – Sign in with Email/Phone](/quickstart-guides/html-magic-link-with-email-and-phone) {% endcontent-ref %} {% content-ref url="/pages/-MCjwlfkbi3ejQQ0qQ4K" %} [React – WebAuthn](/quickstart-guides/react-webauthn) {% endcontent-ref %} # Sign In with Email/Phone Number Our JavaScript SDK offers the easiest way to integrate Cotter 's email/phone verification. You can simply embed Cotter's Login Form and it will do the heavy lifting for you. > **Concepts:** Learn about how [**Sign in with Email/Phone Number**](/features/verify-email-phone) works. ### What you're building ![Cotter's Embeddable Login Form using the JS SDK](/files/-M9M-J5jm5GYC1L6z5P6) ## Try it out {% hint style="info" %} **Quickly try out how it works in our** [**Hello World Example**](https://codesandbox.io/s/client-side-working-example-hiy8w?file=/index.html)**!** πŸŽ‰ {% endhint %} ### Overview Verifying **email and phone number** in your website using our JavaScript SDK consists of the following steps: 1. Embed Cotter in your website 2. Receive a Callback with user's data and a `token` from Cotter 3. Send the `token` to your backend server ## Steps 1. [Setup Cotter](/sdk-reference/web/web-sdk-verify-email-phone#1-setup-cotter) with your `API_KEY_ID` and some config 2. [Show Cotter form](/sdk-reference/web/web-sdk-verify-email-phone#2-show-cotter-form) 3. [Send the Payload](/sdk-reference/web/web-sdk-verify-email-phone#step-3-sending-the-payload-to-your-backend-server) containing the user's information to your backend server ### Step 1: Setup Cotter #### Include Javascript SDK To use our Javascript SDK, include the script below in your HTML page or use the npm package. {% tabs %} {% tab title=" ``` Make sure you check for the latest version at {% endtab %} {% tab title="npm" %} ``` npm install cotter --save ``` {% endtab %} {% tab title="yarn" %} ``` yarn add cotter ``` {% endtab %} {% endtabs %} #### Initialize Cotter Initialize Cotter in your Login page. If using HTML, put this script at the **bottom** of your `` . If you're using React, put this in `useEffect` or `componentDidMount` . We want this script to run right after the page is loaded. {% tabs %} {% tab title="HTML" %} ```javascript ``` {% endtab %} {% tab title="React" %} ```javascript import Cotter from "cotter"; // 1️⃣ Import Cotter //... useEffect(() => { var cotter = new Cotter(API_KEY_ID); // πŸ‘ˆ Specify your API KEY ID here cotter .withFormID("form_default") // Use customization for form "form_default" .signInWithLink() // to send a verification code, use .signInWithOTP() .showEmailForm() // to send via phone number use .showPhoneForm() .then(payload => { // payload is Cotter's token containing user information console.log("Cotter User Information", payload); // ================================== // TODO: Login to backend // ================================== }) .catch(err => console.log(err)); }, []); ``` {% endtab %} {% endtabs %} **Adding more fields** You can also [**add more fields**](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#additional-fields), customize the styles, and intercept the authentication request before it's sent. Check out how to [Customize the Form](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization). **Send Code via WhatsApp** Instead of using SMS, you can also send the code via WhatsApp. Go to the [Dashboard](https://dev.cotter.app/) > Branding and chose "Phone" on top of the preview. {% hint style="info" %} To send code/link via SMS or WhatsApp, you'll need to add some balance to you project in the [Dashboard](https://dev.cotter.app/). {% endhint %} ### Step 2: Show Cotter Form **Add the `
` container with id "cotter-form-container"** {% tabs %} {% tab title="HTML" %} ```markup
``` {% endtab %} {% tab title="React" %} ```markup {/* 3️⃣ Put a
that will contain the form */}
``` {% endtab %} {% endtabs %} ### What we have so far {% tabs %} {% tab title="HTML" %} ```markup
``` {% endtab %} {% tab title="React" %} ```javascript import React, { useEffect } from "react"; import Cotter from "cotter"; // 1️⃣ Import Cotter function App() { // 2️⃣ Initialize and show the form useEffect(() => { var cotter = new Cotter(API_KEY_ID); // πŸ‘ˆ Specify your API KEY ID here cotter .withFormID("form_default") // Use customization for form "form_default" .signInWithLink() .showEmailForm() .then(payload => { console.log("Cotter User Information", payload); // TODO: Login to server }) .catch(err => console.log(err)); }, []); return (
{/* 3️⃣ Put a
that will contain the form */}
); } export default App; ``` {% endtab %} {% endtabs %} ### Step 3: Sending the Payload to your Backend Server You can get the authentication response in the `then` callback function and send it to your server. For example: ```javascript var cotter = new Cotter(""); cotter .withFormID("form_default") // Use customization for form "form_default" .signInWithLink() .showEmailForm() .then(payload => { console.log("Cotter User Information", payload); // TODO: Login to Server axios .post("http://localhost:3005/login", payload) .then((resp) => console.log("Response From Server", resp)) .catch((err) => console.log(err)); }) .catch(err => console.log(err)); ``` The `payload` that you receive from the promise is a JSON Object with the following format: ```javascript { "email": "myemail@gmail.com", // User's email (or phone number) "oauth_token": { "access_token": "eyJhbGciOiJFUzI1NiIsImt...", // Access Token to validate "id_token": "eyJhbGciOiJFUzI1Ni...", "refresh_token": "27805:CNf76faa8trMhjXM...", "expires_in": 3600, "token_type": "Bearer", "auth_method": "OTP" }, "user": { "ID": "abcdefgh-abcd-abcd-abcd-af6f81fb5432", // [Deprecated] Cotter User ID "created_at": "2020-07-21T05:50:14.182738Z", "updated_at": "2020-07-21T06:00:47.115096Z", "deleted_at": "0001-01-01T00:00:00Z", "issuer": "", "identifier": "myemail@gmail.com" } } ``` {% hint style="warning" %} Please use the identifier (email/phone number) as your main way to identify users, **user.ID is deprecated.** {% endhint %} {% hint style="info" %} You should [verify the access token ](/getting-access-token/verifying-jwt-tokens)to ensure this is valid and it comes from Cotter's server. {% endhint %} ### Handling the response in your backend {% content-ref url="/pages/-MDcFwnPyQzT3MiP1tHe" %} [Backend: Handling Response](/sdk-reference/backend-handling-response) {% endcontent-ref %} ## πŸŽ‰ You're done! ## Securing your Project Since you'll be using your API Key from a front-end website or mobile app, your `API_KEY_ID` is exposed to anyone inspecting your code. Here are some ways to prevent abuse: * [Only allow your website/app to use your API Key](/protecting-your-account/only-allow-your-website-app-to-use-your-api-key) * [Rate Limit the number of authentication requests](/protecting-your-account/rate-limit) * [Enable reCAPTCHA to prevent automated abuse](/protecting-your-account/enable-recaptcha-to-protect-against-automated-abuse) ## What's Next * [**Styling the Form**](/sdk-reference/web/web-sdk-verify-email-phone/styling)**:** You can add Styling from the dashboard or add custom CSS * [**Add Additional Fields**](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#additional-fields)**:** Add fields like Name, Address, etc to the login form * [**Check the email/phone before logging in**](/sdk-reference/web/web-sdk-verify-email-phone/checking-the-email-or-phone-before-sending-a-verification-code): Useful for employees-only portals, RSVP, waitlists, checking if the user is registered, etc. # Customize the Form ## Customize the Form from the Dashboard You can now customize the form from [Cotter's Dashboard](https://dev.cotter.app/) > Project > Design. ![](/files/-MXtivfWqAyXySH8FbeI) **Customizable Features that are not available in the Dashboard:** * [Add Additional fields](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#additional-fields) * [Advanced Styling](/sdk-reference/web/web-sdk-verify-email-phone/styling) ## Advanced Configuration Reference You can use our advanced config to have more functionality: #### Usage: ```javascript var cotter = new Cotter(config); // πŸ‘ˆ Put the config in here cotter .signInWithLink() .showEmailForm() .then(payload => {}) .catch(err => {}); ``` #### Config: Here's an example of a complete configuration: ```javascript var config = { // Required Basic Configuration ApiKeyID: "", Type: "PHONE", // EMAIL or PHONE ContainerID: "cotter-container-signup", IdentifierField: "phone", // Change Country Code CountryCode: ["+62"], // IT HAS TO BE AN ARRAY // Styling ButtonBackgroundColor: "#000000", ButtonTextColor: "#ffffff", ButtonText: "Sign Up Now", ButtonBorderColor: "#D2D3FF", // don't specify for no border // Adding fields AdditionalFields: [ { label: "Full Name", name: "name", placeholder: "Enter your full name" } ], // Intercepting before authentication is processed OnBegin: payload => { if (payload.identifier != "+12345678910") { return "Phone Number is not allowed"; } return null; }, // Add WhatsApp option to send verification code // (only for type = PHONE) // ################################################ // # πŸ‘ˆPlease read the section about WhatsApp πŸ‘ˆ # // # to comply with WhatsApp's Policy # // ################################################ PhoneChannels: ["SMS", "WHATSAPP"], // default = ["SMS"] // WhatsApp Button Styling ButtonWAText: "Continue with", ButtonWATextSubtitle: "Tell your customer that you'll be sending the verification code via WhatsApp", ButtonWABackgroundColor: "#128C7E", ButtonWABorderColor: "#075E54", ButtonWATextColor: "#ffffff", ButtonWALogoColor: "white", }; ``` ## **Description** | Field Name | Description | Required | | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | ApiKeyID | your `API_KEY_ID` | Y | | Type | `"EMAIL"` or `"PHONE"` | Y | | ContainerID | `id` of the `
` where you want to serve Cotter Form. | Y | | ButtonBackgroundColor | Button background color. Use HEX format (e.g. `#000000`) | N | | ButtonTextColor | Button text color. Use HEX format (e.g. `#FFFFFF`) | N | | ButtonText | Button text. Default is "Sign Up Without Password" | N | | [AdditionalFields](/sdk-reference/web/web-sdk-verify-email-phone#additional-fields) | Additional fields that you want to include in the JSON obj. Check the specs for [Additional Fields Object](/sdk-reference/web/web-sdk-verify-email-phone#additional-fields) below | N | | IdentifierField | Field name for the identifier to include in the JSON obj. For example, if you want to include the phone number in the JSON obj under key `"phone"`, then fill in `IdentifierField = "phone"` | Y | | [OnBegin](/sdk-reference/web/web-sdk-verify-email-phone#onbegin) | A function that will be called before the signup process begin. Check the specs for [OnBegin](/sdk-reference/web/web-sdk-verify-email-phone#onbegin) below | N | | [CountryCode](/sdk-reference/web/web-sdk-verify-email-phone#countrycode) | **An Array** of country code options for the user | N | | PhoneChannels | **An Array** of channels to send verification code to your users. Default value is `["SMS"].`Available values are `SMS` and `WHATSAPP.` For example, to allow both SMS and WhatsApp, specify `["SMS", "WHATSAPP"]` | N | ### **Additional Fields** The additional fields will be used to generate more `` fields for your users. The format is as following: ```javascript var config = { ... AdditionalFields: [ { label: "Full Name", name: "name", placeholder: "Enter your full name" }, { label: "Address", name: "address", placeholder: "Enter your address" }, { label: "Prefilled Info", name: "prefilled", type: "hidden", // type can be "hidden", "text" or "number" initial_value: "autofill value" } ], } ``` > Available types: `hidden`, `text`, `number` This will be sent to you to the [RedirectURL](/sdk-reference/web/web-sdk-verify-email-phone#redirecturl) endpoint above as part of the JSON object. For example, with the fields above, you'll get a JSON object like the following. **JSON Object to be sent to `RedirectURL`:** ```javascript { "token": {...}, [IdentifierField]: "+12345678910", // Additional Fields "name": "Hello World", "address": "Street Address", "prefilled": "autofill value" ... } ``` ### **OnBegin** This function will be invoked before the Signup/Login process. You will receive the following payload as a parameter to your function **Payload passed into your OnBegin function** ```javascript var payload = { identifier: "+12345678910", identifier_type: "PHONE", device_type: "BROWSER", device_name: "Chrome ..." }; ``` You can do a check against the `identifier` here before the form is submitted. If you include `OnBegin` key, you have to either **return an error string**, or **return null** if you want to continue the authentication process: **A. If you want to continue submission:** ```javascript return null; ``` **B. If you want to stop submission with an error:** ```javascript return "Your error message"; ``` Example: ```javascript OnBegin: payload => { if (payload.identifier != "+12345678910") { return "Phone Number is not allowed"; } // No error, continue submission return null; }, ``` ### ### **CountryCode** The default value is `CountryCode: ["+1"];` {% hint style="warning" %} If you specify this, **you have to use an array** even though you only need 1 country code! {% endhint %} ex. with 1 country code ```javascript CountryCode: ["+1"]; ``` ex. with 2 country codes ```javascript CountryCode: ["+62", "+91"]; ``` {% hint style="success" %} Our SMS and WhatsApp messaging works **worldwide**! {% endhint %} # Checking the email or phone before sending a verification code You can call a function to check the entered email or phone before we send a verification code or magic link. ## Use case * You only allow specific list of pre-screened phone numbers or emails * You want to know if the user is already registered, and redirect them to a Login page instead * You want to check if the email is from a certain domain **Check out this** [**example code that only allows business email to login**](https://codesandbox.io/s/html-magic-link-restrict-email-ellxs?file=/index.html)**.** ## Implementation ```javascript var cotter = new Cotter(""); cotter .signInWithLink(myOnBeginFunction) // πŸ‘ˆ Pass in your function here .showEmailForm() .then(payload => {}) .catch(payload => {}); ``` ### The `OnBegin` function specification This function will be invoked before we send the verification code or magic link. You will receive the following payload as a parameter to your function **Payload passed into your OnBegin function** ```javascript var payload = { identifier: "+12345678910", identifier_type: "PHONE", device_type: "BROWSER", device_name: "Chrome ...", client_json: { // This is available if you set up AdditionalFields "name": "Hello World", "address": "Street Address" } }; ``` You can do a check against the `identifier` here before the form is submitted. If you include `OnBegin` key, you have to either **return an error string**, or **return null** if you want to continue the authentication process: **A. If you want to continue submission:** ```javascript return null; ``` **B. If you want to stop submission with an error:** ```javascript return "Your error message"; ``` Example with sync function: ```javascript const myOnBeginFunction = payload => { if (payload.identifier != "+12345678910") { return "Phone Number is not allowed"; } // No error, continue submission return null; } ``` Example with async function: ```javascript const myOnBeginFunction = async (payload)=> { try { let allowed = await checkIfPhoneAllowed(payload.identifier); if (!allowed) { return "Phone Number is not allowed"; } } catch (e) { return e.message; // Make sure this is a string! } // No error, continue submission return null; } ``` ### You should also check the email when Verifying the JWT Token When a user logs in to Cotter, [the SDK generates an `access_token`](/getting-access-token/handling-authentication-with-cotter) that you can send to your backend API to authorize a request. This access token contains the user's email or phone number. **You should check if the email or phone number is allowed to log in in your backend server** [**when validating the JWT token**](/getting-access-token/verifying-jwt-tokens) **in addition to the OnBegin function.** # Sending Code or Link via WhatsApp By default, when the user enters a phone number, we'll send a verification code or magic link using SMS. You can add the option for your users to receive the verification code or link as a WhatsApp message. ## How to Add the WhatsApp Option ![PhoneChannels options](/files/-M4XQyDsEHvFz_lzI2ql) In your [dashboard](https://dev.cotter.app) > Branding, **select the WhatsApp checkbox** for the Magic Link Form tab and OTP Verification Tab. ![Enabling WhatsApp to send a verification code](/files/-MEjZueJr88m3iLy-DDA) ### WhatsApp Opt-In Requirements WhatsApp requires that your application implement explicit user opt-ins to deliver messages over WhatsApp. {% hint style="info" %} ⚠️[**Read WhatsApp Opt-In Requirements**](https://developers.facebook.com/docs/whatsapp/guides/opt-in/) {% endhint %} To do this, we provide the **WhatsApp Button Configuration > Subtitle** to explicitly inform your users that they will be receiving a verification code via WhatsApp. The default value for the **Subtitle** is *"If you choose to login with WhatsApp, we will send a WhatsApp message to this number with a verification code"* {% hint style="danger" %} We make the **Subtitle** customizable so you can **use a language that your customers understand.** Please make sure that your customer is informed that they will be receiving a WhatsApp message, otherwise your application may be suspended. {% endhint %} # Styling ## Styling from the Dashboard Generally, you can customize the form's texts and colors from [Dashboard](https://dev.cotter.app) > Project > Design. ![Customize the design of your login form](/files/-MWQcHEgRhBj89UPBGc7) ## Adding your own CSS {% hint style="success" %} This is now available with **`signInWithOTP`**and **`signInWithLink`** {% endhint %} To style the form, add field `Styles` to the configuration and specify the CSS styling for each element. The styling accepts a JavaScript object with `camelCased` properties rather than a CSS string, for example: ```javascript // You need to pass a `config` object instead of your `API_KEY_ID` to cotter: // 1) Make a Config for adding Styles var config = { ApiKeyID: "", Styles: { input_label: { fontFamily: "Roboto", fontSize: 15, color: "red", fontWeight: 700, }, input_text_container_default: { backgroundColor: "#fce883", padding: "20px 60px", }, input_text: { backgroundColor: "#fce883", fontFamily: "Roboto", fontSize: 20, }, button_container: { borderRadius: 0, }, button_text: { color: "aqua", }, }, // your other config... } // 2) Then pass the config to Cotter var cotter = new Cotter(config); // πŸ‘ˆ Put the config in here cotter .signInWithOTP() .showEmailForm() .then(payload => {}) .catch(err => {}); ``` You can find the element name by checking the `class` of the element you want to style. For reference, here are the elements that you can modify: * `form_container` * `loadingImg` * `input_label` * `verification_label` * `pin_row` * `pin_input` * `verification_subtitle` * `error` * `input_row_container` * `input_row` * `input_text_container_default` * `input_text` * `input_text_container` * `country_code` * `country_code_blank` * `input_text_p` * `check_input` #### Available Fonts Not all fonts are available because the fonts are not loaded inside Cotter's form. These are the list of fonts that you can use: * Roboto * Lato * Overpass * Open Sans * Akkurat * Akkurat-Bold * Poppins * Inter # Older SDK If you're looking for an older version of the documentation, you can find it in the sub pages of this section. # Customize the Form ## Customize the Form from the Dashboard You can now customize the form from [Cotter's Dashboard](https://dev.cotter.app/) > Branding. ![Customizing the Form from Cotter](/files/-MCk6p50lCyKYHP5NYNn) **Customizable Features that are not available in the Dashboard:** * [Add custom fields](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#additional-fields) * [Advanced Styling](/sdk-reference/web/web-sdk-verify-email-phone/styling) ## Advanced Configuration Reference You can use our advanced config to have more functionality: #### Usage: ```javascript var cotter = new Cotter(config); // πŸ‘ˆ Put the config in here cotter .signInWithLink() .showEmailForm() .then(payload => {}) .catch(err => {}); ``` #### Config: Here's an example of a complete configuration: ```javascript var config = { // Required Basic Configuration ApiKeyID: "", Type: "PHONE", // EMAIL or PHONE ContainerID: "cotter-container-signup", RedirectURL: "https://yourwebsite.com/account/create", SkipRedirectURL: false, IdentifierField: "phone", OnSuccess: payload => { // SET Token Cookie/localstorage here window.localStorage.setItem("access_token", payload.access_token); window.localStorage.setItem("refresh_token", payload.refresh_token); window.location.href = "/signin"; }, // Change Country Code CountryCode: ["+62"], // IT HAS TO BE AN ARRAY // Styling ButtonBackgroundColor: "#000000", ButtonTextColor: "#ffffff", ButtonText: "Sign Up Now", ButtonBorderColor: "#D2D3FF", // don't specify for no border // Adding fields AdditionalFields: [ { label: "Full Name", name: "name", placeholder: "Enter your full name" } ], // Intercepting before authentication is processed OnBegin: payload => { if (payload.identifier != "+12345678910") { return "Phone Number is not allowed"; } return null; } // Add WhatsApp option to send verification code // (only for type = PHONE) // ################################################ // # πŸ‘ˆPlease read the section about WhatsApp πŸ‘ˆ # // # to comply with WhatsApp's Policy # // ################################################ PhoneChannels: ["SMS", "WHATSAPP"], // default = ["SMS"] // WhatsApp Button Styling ButtonWAText: "Continue with", ButtonWATextSubtitle: "Tell your customer that you'll be sending the verification code via WhatsApp", ButtonWABackgroundColor: "#128C7E", ButtonWABorderColor: "#075E54", ButtonWATextColor: "#ffffff", ButtonWALogoColor: "white", }; ``` ## **Description** | Field Name | Description | Required | | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | ApiKeyID | your `API_KEY_ID` | Y | | [RedirectURL](/sdk-reference/web/web-sdk-verify-email-phone#redirecturl) | The backend URL where we will send a [JSON obj](/sdk-reference/web/web-sdk-verify-email-phone#redirecturl) containing form information and a token | Y | | [SkipRedirectURL](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#skip-redirecturl) | `true` or `false` . If set to `true`, then it will skip sending the [JSON obj](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#redirecturl) to the RedirectURL, and instead automatically pass it to [`OnSuccess`](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#onsuccess). | | | Type | `"EMAIL"` or `"PHONE"` | Y | | ContainerID | `id` of the `
` where you want to serve Cotter Form. | Y | | ButtonBackgroundColor | Button background color. Use HEX format (e.g. `#000000`) | N | | ButtonTextColor | Button text color. Use HEX format (e.g. `#FFFFFF`) | N | | ButtonText | Button text. Default is "Sign Up Without Password" | N | | [AdditionalFields](/sdk-reference/web/web-sdk-verify-email-phone#additional-fields) | Additional fields that you want to include in the JSON obj. Check the specs for [Additional Fields Object](/sdk-reference/web/web-sdk-verify-email-phone#additional-fields) below | N | | IdentifierField | Field name for the identifier to include in the JSON obj. For example, if you want to include the phone number in the JSON obj under key `"phone"`, then fill in `IdentifierField = "phone"` | Y | | [OnBegin](/sdk-reference/web/web-sdk-verify-email-phone#onbegin) | A function that will be called before the signup process begin. Check the specs for [OnBegin](/sdk-reference/web/web-sdk-verify-email-phone#onbegin) below | N | | [OnSuccess](/sdk-reference/web/web-sdk-verify-email-phone#onsuccess) | A function that will be called when the signup process succeed. It's recommended to set your localStorage/cookies here and redirect to your dashboard. Check the specs for [OnSuccess](/sdk-reference/web/web-sdk-verify-email-phone#onsuccess) below | Y | | [CountryCode](/sdk-reference/web/web-sdk-verify-email-phone#countrycode) | **An Array** of country code options for the user | N | | PhoneChannels | **An Array** of channels to send verification code to your users. Default value is `["SMS"].`Available values are `SMS` and `WHATSAPP.` For example, to allow both SMS and WhatsApp, specify `["SMS", "WHATSAPP"]` | N | ### **RedirectURL** ![Authentication Flow if you use RedirectURL](/files/-M5UW0-ySdRevCZaWiTs) We will send a JSON Object to this backend URL. The JSON Object will have the following format: ```javascript { "token": { "identifier": "+12345678910", "identifier_type": "PHONE", "receiver": "", "expire_at": "1582679175", // Unix timestamp "signature": "7en+KvbLpMkA7Z93K5y3a12tDo2x3n..." //Signature }, [IdentifierField]: "+12345678910", // Additional Fields "field_1": "Value inside field 1", "field_2": "Value inside field 2", ... } ``` Description: **payload.Token** Contains the email or phone number of the user. You should [verify the signature](/sdk-reference/web/web-sdk-verify-email-phone#verifying-the-signature) to ensure that the request comes from Cotter's server. **payload.IdentifierField** This field name will be the same as what you specify in the `config` above. For example, if your `IdentifierField = "PHONE"`, you'll get ```javascript { ... "PHONE": "+12345678910", } ``` **payload.AdditionalFields** The rest will be filled with any additional fields you specify in the `config`. For example if you add fields for `"name"` and `"address"`, you'll get: ```javascript { ... "name": "Hello World", "address": "123 Street", } ``` Read how to specify [Additional Fields Object](/sdk-reference/web/web-sdk-verify-email-phone#additional-fields) below. ### Skip RedirectURL ![Authentication Flow if you use SkipRedirectURL](/files/-M4RUuBaXZjEyuAR32Np) If you want to handle Cotter's token in a function instead of sending it to your backend `redirect_url`, you can specify ```javascript { ... SkipRedirectURL: true, } ``` When this is true, the [JSON payload](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#redirecturl) as specified in RedirectURL section will be passed into your [OnSuccess](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#onsuccess) function. ### **Additional Fields** The additional fields will be used to generate more `` fields for your users. The format is as following: ```javascript var config = { ... AdditionalFields: [ { label: "Full Name", name: "name", placeholder: "Enter your full name" }, { label: "Address", name: "address", placeholder: "Enter your address" }, { label: "Prefilled Info", name: "prefilled", type: "hidden", // type can be "hidden", "text" or "number" initial_value: "autofill value" } ], } ``` > Available types: `hidden`, `text`, `number` This will be sent to you to the [RedirectURL](/sdk-reference/web/web-sdk-verify-email-phone#redirecturl) endpoint above as part of the JSON object. For example, with the fields above, you'll get a JSON object like the following. **JSON Object to be sent to `RedirectURL`:** ```javascript { "token": {...}, [IdentifierField]: "+12345678910", // Additional Fields "name": "Hello World", "address": "Street Address", "prefilled": "autofill value" ... } ``` ### **OnBegin** This function will be invoked before the Signup/Login process. You will receive the following payload as a parameter to your function **Payload passed into your OnBegin function** ```javascript var payload = { identifier: "+12345678910", identifier_type: "PHONE", device_type: "BROWSER", device_name: "Chrome ..." }; ``` You can do a check against the `identifier` here before the form is submitted. If you include `OnBegin` key, you have to either **return an error string**, or **return null** if you want to continue the authentication process: **A. If you want to continue submission:** ```javascript return null; ``` **B. If you want to stop submission with an error:** ```javascript return "Your error message"; ``` Example: ```javascript OnBegin: payload => { if (payload.identifier != "+12345678910") { return "Phone Number is not allowed"; } // No error, continue submission return null; }, ``` ### **OnSuccess** This function will be called **after** the call to `RedirectURL` is successful. Your function will receive the payload returned from `RedirectURL`. It is recommended to set your sessions or cookies here, and then redirect to another page in your website. For example: ```javascript OnSuccess: payload => { // You can set your own sessions for your website window.localStorage.setItem("access_token", payload.access_token); window.localStorage.setItem("refresh_token", payload.refresh_token); window.location.href = "/dashboard"; }; ``` **OnSuccess when SkipRedirectURL is true** When you set `SkipRedirectURL: true` , `OnSuccess` will instead receive the JSON Payload token that was described in [RedirectURL section](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#redirecturl). ### **CountryCode** The default value is `CountryCode: ["+1"];` {% hint style="warning" %} If you specify this, **you have to use an array** even though you only need 1 country code! {% endhint %} ex. with 1 country code ```javascript CountryCode: ["+1"]; ``` ex. with 2 country codes ```javascript CountryCode: ["+62", "+91"]; ``` {% hint style="info" %} Currently, the only available countries are **United States**, **India** and **Indonesia**. Chat us on Intercom if you need other countries, we just need to switch it on. {% endhint %} # Sign in with Social Login Sign in with Social Login allows you to authenticate users using their social accounts like Google, Github, etc. ### What you're building Allow users to sign in with a Social Account, **without getting duplicate accounts.** With Cotter, we automatically link the user's existing account with their Social Account. ![Sign in with Github and Google using Cotter's SDK](/files/-MH_8SXtlVChNPg3Of_Z) ### Key Features * Simple integration, **no additional code**. * **Auto-linking with existing accounts**, users can either log in with their email or with Github and it will go to the same user account. * Connect Social Provider Account from inside your Settings page to allow easy API integrations. (For example, a user never uses the "Sign in with Github", but you need their Github access token to enable deployment: you can ask them to press a button to connect their Github account). ### Overview 1. To enable this feature, you need to first configure [Sign in with Email/Phone Number](/sdk-reference/web/web-sdk-verify-email-phone) as the primary login method. {% content-ref url="/pages/-M0ROJn7tosL9qeumqFd" %} [Sign In with Email/Phone Number](/sdk-reference/web/web-sdk-verify-email-phone) {% endcontent-ref %} 2\. You can then add options for the user to sign in using a Social Login Provider in the Dashboard. #### Available Providers * Github * Google * [Let us know what you need](https://join.slack.com/t/askcotter/shared_invite/zt-dxzf311g-5Mp3~odZNB2DwYaxIJ1dJA) ## Steps 1. Integrate Cotter's Login Form following [Sign in with Email/Phone Number](/sdk-reference/web/web-sdk-verify-email-phone) as the primary login method. 2. [Set up your Social Login](/sdk-reference/web/sign-in-with-social-login-provider#setting-up-social-login-provider). 3. [Connecting a Social Account to an existing user ](/sdk-reference/web/sign-in-with-social-login-provider#connecting-a-social-account-to-an-existing-user)that **didn't use Sign in with a Social Provider** from a button. 4. [Getting the Access Token from the Social Provider](/sdk-reference/web/sign-in-with-social-login-provider#getting-access-tokens-from-the-social-login-provider) to use their API. ## Setting Up Social Login Provider {% hint style="info" %} Make sure you are using the JS Package **version >= 0.3.16** {% endhint %} 1. You will need to create an "App" for the Social Login Provider. Follow the instructions for each login provider. You will need to enter the credentials to [Dashboard](https://dev.cotter.app/) > Social Login * [Github Instructions](/sdk-reference/web/sign-in-with-social-login-provider/github-instructions) * [Google Instructions](/sdk-reference/web/sign-in-with-social-login-provider/google-instructions) 2. Go to [Dashboard](https://dev.cotter.app/) > Project > Form & Fields, check the login provider that you want to enable under "Social Login Providers" and press **Save**. ![](/files/-MWQcmxqcP-fnFc--n12) 4\. That's it, you should now see the "Sign in with Github" button below the email/phone number input. ### Receiving the User Response after successful login You will receive responses the same way as [**Sign in with email/phone**](/sdk-reference/web/web-sdk-verify-email-phone), inside the `then` callback that you provided. ```javascript var cotter = new Cotter(API_KEY_ID); // Specify your API KEY ID here cotter .withFormID("form_default") // Use customization for form "form_default" .signInWithLink() .showEmailForm() .then((response) => { setpayload(response); // πŸ‘ˆ You'll receive the response here, as usual }) .catch((err) => console.log(err)); ``` ## How it works If a user signed-in with Github and the Github username is user1 and the Github email is : * **Case 1 – If a user with Github username `user1` has logged-in before** and already associated with a user (`userID: 123`), then the user can automatically log in. * **Case 2 – If a user with email** [**user1@gmail.com**](mailto:user1@gmail.com) **doesn't exist**: It will create a new user with email , and the user can log in both with their Github account or with email using a magic link or OTP. * **Case 3 – If a user with email** [**user1@gmail.com**](mailto:user1@gmail.com) **already exists**: It will ask the user if they want to link the account for with the Github account. If they agree, the user can always login both with their Github account or with email using a magic link or OTP. ![Case 3: Prompt for the user to connect their existing account with the Github account](/files/-MGMSCjt9Zb2Ur1eQwLM) ### Connecting a Social Account to an existing user You can alternatively **connect the user's Github/Google account when the user is already logged** **in.** For example, your website may have a Settings page, and the user can press a button "Connect Github Login" to allow them to connect their Github Account and use it to log in. Add a button on your website, and call this function to connect the user's Github Account with the currently logged in user. ```javascript const connectToGithub = async () => { var cotter = new Cotter(apiKey) const accessToken = await cotter.tokenHandler.getAccessToken() cotter.connectSocialLogin("GITHUB", accessToken?.token) // pass in the provider's name } ``` ## Getting Access Tokens from the Social Login Provider When your users sign in with Github, Github returns an `access_token` that you can use to call their API. We store this information for you. To get the `access_token` for each user, follow the instructions below: {% content-ref url="/pages/-MGMR-Umubw7gOJeVnX8" %} [Getting Access Tokens from Social Login Providers](/sdk-reference/web/sign-in-with-social-login-provider/getting-access-tokens-from-social-login-providers) {% endcontent-ref %} ## UI Considerations Logging-in to social providers **requires us to redirect the user to the provider's page to login** when necessary. When the login process is done, the users will be redirected back **to the page where you embedded the form**: For example: * Login Page that contains the form: `example.com/login` * User login to Github: redirect to `github.com/oauth/....` * User finish login: redirect back to `example.com/login?code=xyz&state=abc` As you can see, we pass in a `code` and `state` and other parameters when redirecting back to your login page. **Cotter's Login Form automatically handles this query parameters** for you and will resolve the Promise with the usual Cotter user information response. **With that said, make sure your UI takes into account that the user will be redirected away and then back to your login page.**
# Getting Access Tokens from Social Login Providers Cotter stores all OAuth Tokens that are returned from the Social Login Providers when a user sign in. You can retrieve the tokens using the following API Requests. ## Get a List of Access Tokens from All Social Logins for a User `GET` `https://www.cotter.app/api/v0/oauth/token/list/:cotter_user_id` This will give you a list of access tokens that the user has for each social login provider that is associated with their account. #### Path Parameters | Name | Type | Description | | ---------------- | ------ | ------------------------- | | cotter\_user\_id | string | The user's Cotter User ID | #### Headers | Name | Type | Description | | ---------------- | ------ | ------------------- | | API\_KEY\_ID | string | Your API Key ID | | API\_SECRET\_KEY | string | Your API Secret Key | {% tabs %} {% tab title="200 A list of OAuth Tokens from each provider that is associated with the user. " %} ```javascript [ { "ID": "abcdefgh-abcd-abcd-abcd-24339e5457ff", // OAuth Token ID "created_at": "2020-09-04T04:51:10.778976Z", "updated_at": "2020-09-04T04:51:10.778977Z", "deleted_at": "0001-01-01T00:00:00Z", "company_id": "abcdefgh-abcd-abcd-abcd-f901315ad31b", // Your API KEY ID "user_id": "abcdefgh-abcd-abcd-abcd-22bc178867ef", // The user's ID "provider_user_id": "20483939", // User ID from the Provider (Github User ID) "provider_username": "putrikarunia", // Login/username from the provider (Github Username) "identity_provider": "GITHUB", "tokens": { // OAuth tokens returned by the provider "access_token": "abcdefghabcdefghabcdefghabcdefghabcdefg", "scope": "repo,user", "token_type": "bearer" } }, { "ID": "abcdefgh-abcd-abcd-abcd-24339e5457ff", // OAuth Token ID "created_at": "2020-09-04T04:51:10.778976Z", "updated_at": "2020-09-04T04:51:10.778977Z", "deleted_at": "0001-01-01T00:00:00Z", "company_id": "abcdefgh-abcd-abcd-abcd-f901315ad31b", // Your API KEY ID "user_id": "abcdefgh-abcd-abcd-abcd-22bc178867ef", // The user's ID "provider_user_id": "20483939", // User ID from the Provider (Github User ID) "provider_username": "putrikarunia", // Login/username from the provider (Github Username) "identity_provider": "GOOGLE", "tokens": { // OAuth tokens returned by the provider "access_token": "abcdefghabcdefghabcdefghabcdefghabcdefgh", "scope": "repo,user", "token_type": "bearer" } }, ... ] ``` {% endtab %} {% endtabs %} ## Get an Access Token from a Specific Provider for a User `GET` `https://www.cotter.app/api/v0/oauth/token/:provider_name/:cotter_user_id` Get an access token from one provider for the user. #### Path Parameters | Name | Type | Description | | ---------------- | ------ | ------------------------- | | cotter\_user\_id | string | The user's Cotter User ID | | provider\_name | string | One of: `GITHUB` | #### Headers | Name | Type | Description | | ---------------- | ------ | ------------------- | | API\_KEY\_ID | string | Your API Key ID | | API\_SECRET\_KEY | string | Your API Secret Key | {% tabs %} {% tab title="200 A Token Object with the OAuth tokens from the provider for the user." %} ```javascript { "ID": "abcdefgh-abcd-abcd-abcd-24339e5457ff", // OAuth Token ID "created_at": "2020-09-04T04:51:10.778976Z", "updated_at": "2020-09-04T04:51:10.778977Z", "deleted_at": "0001-01-01T00:00:00Z", "company_id": "abcdefgh-abcd-abcd-abcd-f901315ad31b", // Your API KEY ID "user_id": "abcdefgh-abcd-abcd-abcd-22bc178867ef", // The user's ID "provider_user_id": "20483939", // User ID from the Provider (Github User ID) "provider_username": "putrikarunia", // Login/username from the provider (Github Username) "identity_provider": "GITHUB", "tokens": { // OAuth tokens returned by the provider "access_token": "abcdefghabcdefghabcdefghabcdefghabcdefg", "scope": "repo,user", "token_type": "bearer" } } ``` {% endtab %} {% endtabs %} ## Delete an Access Token from a Specific Provider for a User `DELETE` `https://www.cotter.app/api/v0/oauth/token/:provider_name/:cotter_user_id` Delete an access token from a provider for the user. #### Path Parameters | Name | Type | Description | | ---------------- | ------ | ------------------------- | | cotter\_user\_id | string | The user's Cotter User ID | | provider\_name | string | One of: `GITHUB` | #### Headers | Name | Type | Description | | ---------------- | ------ | ------------------- | | API\_KEY\_ID | string | Your API Key ID | | API\_SECRET\_KEY | string | Your API Secret Key | {% tabs %} {% tab title="200 " %} ``` { "ID": "00000000-0000-0000-0000-000000000000", "created_at": "0001-01-01T00:00:00Z", "updated_at": "2020-09-04T05:09:16.136898006Z", "deleted_at": "2020-09-04T05:09:16.13689443Z", "company_id": "00000000-0000-0000-0000-000000000000", "user_id": "00000000-0000-0000-0000-000000000000", "provider_user_id": "", "provider_username": "", "identity_provider": "", "tokens": null } ``` {% endtab %} {% endtabs %} # Github Instructions How to get a Client ID and Client Secret from Github, and what to fill in for the Authorization Callback URL. ## Making Github OAuth Apps 1. Go to the [Dashboard](https://dev.cotter.app/) > Social Login > New Login Connection > Github. 2. Follow [Github's instruction on making a Github OAuth App](https://docs.github.com/en/developers/apps/creating-an-oauth-app). Enter your website/app's information as instructed. 3. At Step 8 about **Authorization callback URL**, enter the following: `https://www.cotter.app/api/v0/oauth/token/callback/GITHUB` 4. Copy your Client ID, Client Secret Key, and [Scopes](https://docs.github.com/en/developers/apps/scopes-for-oauth-apps) to your Dashboard > Social Login > Github: ![Enter your Client ID, Client Secret, and Scopes](/files/-MGMOSGx-ajL6KE9Bh8k) ### That's it! Go back to the [Social Login instructions](/sdk-reference/web/sign-in-with-social-login-provider#setting-up-social-login-provider) to finish your setup. # Google Instructions How to get a Client ID and Client Secret from Google OAuth, and what to fill in for the Authorized redirect URIs. ### Create Google OAuth 2.0 Credentials 1. Go to the [Google Credentials page](https://console.developers.google.com/apis/credentials). 2. Click **Create credentials > OAuth client ID**. 3. If you're asked to **Configure Consent Screen**, make sure you choose **External** User Type, and enter your app's information. 4. Select the **Web application** application type. 5. Name your OAuth 2.0 client. 6. Add your website URL as Authorized JavaScript origins. 7. Add `https://www.cotter.app/api/v0/oauth/token/callback/GOOGLE` as the **Authorized redirect URIs.** 8. Click **Create.** 9. Copy your Client ID and Client Secret to your Dashboard > Social Login > Google, then add the [Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) that you need. ![](/files/-MH_FtedP3WRlU8TceOG) 8\. Go to the OAuth consent screen section in Google's console, make sure the **User type** is **External** to allow any user with a Google account, then verify the [OAuth Consent Screen at Google's console](https://console.developers.google.com/apis/credentials/consent). ![](/files/-MXp040PzHFif7iggmRf) ### That's it! Go back to the [Social Login instructions](/sdk-reference/web/sign-in-with-social-login-provider#setting-up-social-login-provider) to finish your setup. # Sign In with WebAuthn Sign in with WebAuthn allows you to authenticate users using TouchID or Windows Hello from their browser. This means, you can use biometric authentication from your website. > **Concepts:** Learn about how [**Sign in with WebAuthn**](/features/sign-in-with-webauthn) works. ![WebAuthn with Cotter's JS SDK](/files/-MCkIqSr1NpqGEsST7of) ### Overview WebAuthn authentication works the following way: 1. A new user would be prompted to either enter a verification code or magic link sent to their email or phone. 2. Once the user verified their email/phone, the SDK will automatically prompt the user if they want to register this device for fast logins next time. 3. The user can press "Enable TouchID" and successfully register their laptop. 4. When the user login next time, the user will automatically be prompted to use TouchID to login. As a fallback method, the user can choose to send a link or code to their email/phone instead. ## Steps ### Step 1: Import Cotter #### Include Javascript SDK To use our Javascript SDK, include the script below in your HTML page or use the npm package. {% tabs %} {% tab title=" ``` Make sure you check for the latest version at {% endtab %} {% tab title="npm" %} ``` npm install cotter --save ``` {% endtab %} {% tab title="yarn" %} ``` yarn add cotter ``` {% endtab %} {% endtabs %} ### Step 2: Set up a `div` element to contain cotter's form {% tabs %} {% tab title="HTML" %} ```markup
``` {% endtab %} {% tab title="React" %} ```markup {/* 2️⃣ Setup a div to contain the form */}
``` {% endtab %} {% endtabs %} Please note that **id** has to be `cotter-form-container` for the form to show up. ### Step 3: Initialize Cotter and show the form Grab your `API_KEY_ID` from [the dashboard](https://dev.cotter.app), then replace `` with your `API_KEY_ID`. {% tabs %} {% tab title="HTML" %} ```markup ``` {% endtab %} {% tab title="React" %} ```javascript import Cotter from "cotter"; //... useEffect(() => { // 3️⃣ Show the form var cotter = new Cotter(""); // πŸ‘ˆ Specify your API KEY ID here cotter .withFormID("form_default") // Use customization for form "form_default" .signInWithWebAuthnOrLink() // or signInWithWebAuthnOrOTP() .showEmailForm() // or showPhoneForm() .then((payload) => console.log(payload)) .catch((err) => console.log(err)); }, []); ``` {% endtab %} {% endtabs %} There are several options for the fallback method: * Method: * Magic Link: use `signInWithWebAuthnOrLink()` * OTP: use `signInWithWebAuthnOrOTP()` * Channel: * Email: use `showEmailForm()` * Phone: use `showPhoneForm()` (you can send code/link via SMS or WhatsApp by setting it up in Dashboard > Branding) ## πŸŽ‰ You're done! # Register WebAuthn for a logged-in user The login form automatically prompt the user to register WebAuthn, however, it's possible that the user dismissed it. {% hint style="warning" %} The following guide only works with [Cotter's NPM package](https://www.npmjs.com/package/cotter) that can be installed using: ```markup yarn add cotter npm i cotter --save ``` This feature is **not supported** on imports using ```markup ``` {% endhint %} **To add the option to register WebAuthn in your Settings page**, you can do the following: #### 1. Check if WebAuthn is available WebAuthn is supported in some browsers like Google Chrome, but not all browsers and not all devices supports it. **Do the following to decide whether or not to show the button to setup WebAuthn:** ```javascript // 1) Check if WebAuthn is available Cotter.isWebAuthnAvailable().then(available => setwebauthnAvailable(available) ); ``` #### 2. Register this device for WebAuthn If WebAuthn is available, you can register WebAuthn for the user on button press: ```javascript var cotter = new Cotter(API_KEY_ID) var user = cotter.getLoggedInUser() // Get the logged-in user if (user) { // If there's a logged-in user user .registerWebAuthn() // register WebAuthn .then(resp => console.log(resp)) .catch(err => console.log(err)) } ``` # Sign In with Device Our JavaScript SDK offers the easiest way to add "Sign in with device" into your website. 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**](/features/passwordless-login) works. {% hint style="warning" %} There are major updates planned for this feature. [Contact us in Slack](https://join.slack.com/t/askcotter/shared_invite/zt-dxzf311g-5Mp3~odZNB2DwYaxIJ1dJA) so we can help you prepare for it. {% endhint %} ### Overview Authenticating users using Trusted Devices with Cotter's JavaScript SDK consists of the following steps: 1. Embed Cotter in your website 2. Receive a Callback with user's authentication event and a `token` from Cotter 3. Validate the token and proceed with logins or transactions. Keep in mind that this works if you have a companion app that [allows users to register their device as a Trusted Device.](/features/passwordless-login/how-it-works) ### What you're building ![Cotter's Authentication Request Modal](/files/-M3o22jdQ1gCzqvmCvSx) There are 2 ways to present Cotter's authentication prompt from your website: * **In the Login form**: after entering their email/phone number, if there's a trusted device, it will automatically prompt the user to approve the login from their device. * **As a popup**: When a user triggers an action that requires authentication, like doing a transaction or opening sensitive information, you can open a popup that will ask the user to approve the transaction from their device. In both cases, you will receive an Event Response (the same event response that you'll receive in mobile app) that you can pass in your backend server during the login/transaction function and check if the user has authenticated and approved the event. ## Required Steps 1. [Allow Trusted Devices and OTP methods in your dashboard](/sdk-reference/web/web-sdk-passwordless-login#step-1-setting-authentication-methods) 2. [Show Login Form or Pop Up Prompt](/sdk-reference/web/web-sdk-passwordless-login#show-the-login-form-or-popup-prompt) ### Step 1: Setting Authentication Methods You need to set allowed methods for authenticating your users. To allow `TRUSTED DEVICES` (and `OTP` if you want to allow it as a fallback method), go to ![Allow Trusted Devices (and OTP)](/files/-M3o60_0FqlqITY2Rqrz) {% hint style="warning" %} Remember to set the correct Project in the dropdown list {% endhint %} ### **Step 2: Show the Login Form or Popup Prompt** We will cover the Login Form here, and the Pop Up in the next guide. * [Steps for Login Form](/sdk-reference/web/web-sdk-passwordless-login#steps-for-login-form) * [Steps for Pop Up Prompt](/sdk-reference/web/web-sdk-passwordless-login/steps-for-pop-up-authentication-prompt) ## Steps for Login Form ![Cotter's Login Form using Trusted Device](/files/-M3oL1aDSso5gULXOKXD) 1. [Setup Cotter](/sdk-reference/web/web-sdk-passwordless-login#1-setup-cotter) with your `API_KEY_ID` and some config 2. [Show Cotter form](/sdk-reference/web/web-sdk-passwordless-login#2-show-cotter-form) 3. [Receive a Callback](/sdk-reference/web/web-sdk-passwordless-login#step-3-receive-callback-in-your-redirecturl) in your `OnSuccess` function the authentication event and a `signature` from Cotter in your backend server ### Step 1: Setup Cotter #### Include Javascript SDK To use our Javascript SDK, include the script below in your HTML page. ```markup ``` #### Initialize Cotter Initialize Cotter in your HTML page, below the script you imported above. For React apps, initialize this in `index.html`. You can use it later in any of your pages. ```markup ``` #### Configuration Here's a basic configuration example: ```javascript var config = { ApiKeyID: "", // Type of identity your want to collect: EMAIL or PHONE Type: "PHONE", // div id of the container for Cotter Form ContainerID: "cotter-container-login", SkipRedirectURL: true, // the JSON key for the phone number or email to be posted to RedirectURL // Read more on RedirectURL JSON Object below IdentifierField: "phone", // OnBegin here is MANDATORY // You need to return the Cotter User ID. (If you used client_user_id, // use that instead). OnBegin: async payload => { var { userID, err } = await getUserIDFromIdentifier( payload.identifier ); return { userID: userID, err: err }; }, // After the user successfully logged-in, the SDK will return a payload // about the login request into this OnSuccess function. OnSuccess: payload => { console.log(payload) }, // (optional) Allow login using OTP sent to email or phone number // if user doesn't have Trusted Device set up // or if user choose to use OTP instead of trusted device // (To enable this, you have to set OTP true in the dashboard) AllowOTPFallback: true, }; // Getting the User ID usnig Cotter's API const getUserIDFromIdentifier = async (identifier) => { try { const resp = await fetch( `https://www.cotter.app/api/v0/user?identifier=${encodeURIComponent( identifier )}`, { headers: { API_KEY_ID: apiKey } } ); const respJSON = await resp.json(); const nullUUID = "00000000-0000-0000-0000-000000000000"; return { userID: respJSON.ID === nullUUID ? null : respJSON.client_user_id, err: respJSON.ID === nullUUID ? "User not found" : null }; } catch (e) { return { userID: null, err: e.message }; } }; ``` **Advanced Customization** [Check out how you can customize the form and change the configuration](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization). ### Step 2: Show Cotter Form To show the cotter form, **1. Add the `
` container.** Put a `
` with the `id` you specified above as `ContainerID` inside your page. For example, if your `"ContainerID": "cotter-container-login"`, put this in your html: ```markup
``` **2. Show the form** ```markup ``` ### What we have so far {% code title="index.html" %} ```markup
``` {% endcode %} ### Step 3: Receive the Response in your OnSuccess function We will send a JSON Object describing the Authentication Event to your `OnSuccess` function. The JSON Object will have the following format: ```javascript { "ID": 2397, "CreatedAt": "2020-04-01T05:28:12.540127Z", "UpdatedAt": "2020-04-01T05:28:16.599833Z", "DeletedAt": null, "client_user_id": "", "issuer": "", "event": "LOGIN_WEB", "ip": "123.347.26.236", "location": "San Mateo", "timestamp": "1585718892", "method": "TRUSTED_DEVICE", "new": false, "approved": true, "signature": "reBafVsmpxO7km5jpRQ3xA..." } ``` {% hint style="info" %} You should [verify the signature ](/sdk-reference/web/web-sdk-passwordless-login#validate-cotters-event-response)in the event response to ensure this is valid and it comes from Cotter's server. {% endhint %} ## Validate Cotter's Event Response Learn how to validate Cotter's event response here: {% content-ref url="/pages/-M2pWffm56vOPZk07RZ7" %} [Validating Cotter's Event Response](/older-api/validating-cotters-event-response) {% endcontent-ref %} ## πŸŽ‰ You're done! ## Next Steps {% content-ref url="/pages/-M3o4Cgu-uvdZvuU7AgZ" %} [Steps for Pop Up Authentication Prompt](/sdk-reference/web/web-sdk-passwordless-login/steps-for-pop-up-authentication-prompt) {% endcontent-ref %} {% content-ref url="/pages/-M3oW3WPjWEiptnzU4qQ" %} [Advanced Customization for Login Form](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization) {% endcontent-ref %} # Steps for Pop Up Authentication Prompt Show a popup to prompt users to authenticate using a Trusted Device before proceeding with a transaction or opening sensitive information In this guide, we'll go over how to show a Pop Up that prompts the user to authenticate with their trusted device before moving forward with an action. ### What you're building ![Cotter's Authentication Request Modal](/files/-M3o22jdQ1gCzqvmCvSx) {% hint style="info" %} Make sure you have done the [Required Steps](/sdk-reference/web/web-sdk-passwordless-login#required-steps) before you proceed. {% endhint %} ## Steps 1. [Setup Cotter](/sdk-reference/web/web-sdk-passwordless-login/steps-for-pop-up-authentication-prompt#step-1-setup-cotter) with your `API_KEY_ID` and some config 2. [Show Cotter form](/sdk-reference/web/web-sdk-passwordless-login/steps-for-pop-up-authentication-prompt#2-show-cotter-form) 3. [Receive a Event Response in `OnSuccess`](/sdk-reference/web/web-sdk-passwordless-login/steps-for-pop-up-authentication-prompt#step-3-receive-event-response-callback) ### Step 1: Setup Cotter #### Include Javascript SDK To use our Javascript SDK, include the script below in your HTML page. ```markup ``` #### Initialize Cotter Initialize Cotter in your HTML page, below the script you imported above. For React apps, initialize this in `index.html`. You can use it later in any of your pages. ```markup ``` #### Configuration Here's a basic configuration example: ```javascript var config = { ApiKeyID: "", // (optional) The email/phone number of your user // (used to send OTP as fallback method) Identifier: "putrikarunian@gmail.com", IdentifierType: "EMAIL", // type of Identifier above (EMAIL or PHONE) // The Cotter User ID of this user UserID: "", // Allow login using OTP sent to email or phone number // if use doesn't have Trusted Device set up // or if user choose to use OTP instead of trusted device // (To enable this, you have to set OTP true in the dashboard) AllowOTPFallback: true, // OnSuccess here will receive the JSON Event Response as a result // of the user Authenticating from their trusted device // You should send this JSON Event Response to your backend OnSuccess: async payload => { // For example, send this payload and the transaction data to submit // a transaction, and validate the payload in your backend console.log(payload); // NOTE: The popup will immediately close, so set a Loading in your // frontend while submitting data to your backend } }; ``` **Advanced Customization** [Check out how you can customize the form and change the configuration](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization-for-pop-up-authentication-prompt). ### Step 2: Show Cotter Auth Request Pop Up To show the the popup ```markup ``` ### What we have so far ```markup
Open Auth Request Popup
``` ### Step 3: Receive Event Response Callback We will pass a JSON Object describing the Authentication Event to your `OnSuccess` function. The JSON Object will have the following format: ```javascript { "ID": 2397, "CreatedAt": "2020-04-01T05:28:12.540127Z", "UpdatedAt": "2020-04-01T05:28:16.599833Z", "DeletedAt": null, "client_user_id": "", "issuer": "", "event": "LOGIN_WEB", "ip": "123.347.26.236", "location": "San Mateo", "timestamp": "1585718892", "method": "TRUSTED_DEVICE", "new": false, "approved": true, "signature": "reBafVsmpxO7km5jpRQ3xA..." } ``` {% hint style="info" %} You should [verify the signature](/sdk-reference/web/web-sdk-passwordless-login/steps-for-pop-up-authentication-prompt#validate-cotters-event-response) in the event response to ensure this is valid and it comes from Cotter's server. {% endhint %} On this step, you should pass this payload to your backend together with any data you need to submit a transaction, or any other api calls to your server. ## Validate Cotter's Event Response Learn how to validate Cotter's event response here: {% content-ref url="/pages/-M2pWffm56vOPZk07RZ7" %} [Validating Cotter's Event Response](/older-api/validating-cotters-event-response) {% endcontent-ref %} ## :tada: You're done! ## Next Steps Customize your Pop Up prompt {% content-ref url="/pages/-M3ob6vjow8Bwd5zU9zY" %} [Advanced Customization for Pop Up Authentication Prompt](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization-for-pop-up-authentication-prompt) {% endcontent-ref %} # Advanced Customization for Login Form ## Configuration Reference Here's an example of a complete configuration: ```javascript var config = { // Required Basic Configuration ApiKeyID: "", Type: "PHONE", ContainerID: "cotter-container-login", RedirectURL: "https://yourwebsite.com/account/create", IdentifierField: "phone", OnSuccess: payload => { window.localStorage.setItem("session", payload.session); window.location.href = "/dashboard"; } OnBegin: async payload => { var userID = await this.getUserIDFromPhone(payload.identifier); return { userID: userID, err: null }; }, // --------- // Change Country Code CountryCode: ["+62"], // IT HAS TO BE AN ARRAY // Styling ButtonBackgroundColor: "#000000", ButtonTextColor: "#ffffff", ButtonText: "Sign Up Now", ErrorColor: "#ff0000", // Event Name in the Event Response EventName: "LOGIN_EMPLOYEE", // Allow OTP as a fallback method for TrustedDevice AllowOTPFallback: true, // Skipping RedirectURL and receive event response in OnSuccess SkipRedirectURL: true, // Change the prompt message AuthRequestText: { title: "Approve this login from your phone", subtitle: "A notification is sent to your trusted device to confirm it's you", image: "https://yourwebsite.com/image.png", titleError: "Something went wrong", subtitleError: "We are unable to confirm it's you, please try again", imageError: "https://yourwebsite.com/image.png", imageSuccess: "https://yourwebsite.com/image.png", switchOTPText: "Authenticate with OTP instead" }, // Receive error message OnError: payload => { console.log("ERROR", payload); } }; ``` ## **Description** | Field Name | Description | Required | | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | ApiKeyID | your `API_KEY_ID` | Y | | [RedirectURL](/sdk-reference/web/web-sdk-verify-email-phone#redirecturl) | The backend URL where we will send a [JSON obj](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization#redirecturl) containing form information and a token | Y | | Type | `"EMAIL"` or `"PHONE"` | Y | | ContainerID | `id` of the `
` where you want to serve Cotter Form. | Y | | [OnBegin](/sdk-reference/web/web-sdk-verify-email-phone#onbegin) | A function that will be called before the login process begin. Return UserID and error if applicable. Check the specs for [OnBegin](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization#onbegin) below. | Y | | [SkipRedirectURL](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization#skip-redirecturl) | `true` or `false` . If set to `true`, then it will skip sending the [JSON obj](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization#redirecturl) to the RedirectURL, and instead automatically pass it to [`OnSuccess`](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization#onsuccess). | N | | ButtonBackgroundColor | Button background color. Use HEX format (e.g. `#000000`) | N | | ButtonTextColor | Button text color. Use HEX format (e.g. `#FFFFFF`) | N | | ButtonText | Button text. Default is "Sign Up Without Password" | N | | ErrorColor | Text color for error messages. Use HEX format (e.g. `#FFFFFF`) | N | | EventName | Tag this authentication event with a name, like `WITHDRAWAL` to make it easier to segment your event logs. | N | | IdentifierField | Field name for the identifier to include in the JSON obj. For example, if you want to include the phone number in the JSON obj under key `"phone"`, then fill in `IdentifierField = "phone"` | Y | | AllowOTPFallback | Allow user to choose to authenticate using OTP (One-Time-Password) instead of Trusted Device if they want. | N | | [OnSuccess](/sdk-reference/web/web-sdk-verify-email-phone#onsuccess) | A function that will be called when the signup process succeed. It's recommended to set your localStorage/cookies here and redirect to your dashboard. Check the specs for [OnSuccess](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization#onsuccess) below | Y | | [CountryCode](/sdk-reference/web/web-sdk-verify-email-phone#countrycode) | **An Array** of country code options for the user | N | | AuthRequestText | A dictionary to customize the text in the authentication prompt | N | | OnError | A function that will be called if there's an error, and will receive the error message or object | N | ### **RedirectURL** We will send a JSON Object to this backend URL. The JSON Object will have the following format: ```javascript { "ID": 2397, "CreatedAt": "2020-04-01T05:28:12.540127Z", "UpdatedAt": "2020-04-01T05:28:16.599833Z", "DeletedAt": null, "client_user_id": "", "issuer": "", "event": "LOGIN_WEB", "ip": "123.347.26.236", "location": "San Mateo", "timestamp": "1585718892", "method": "TRUSTED_DEVICE", "new": false, "approved": true, "signature": "reBafVsmpxO7km5jpRQ3xA..." } ``` Description: **payload.client\_user\_id** Contains your user's `user_id` that you used when registering the user to Cotter. This should be the `user_id` from your backend. **payload.event** The event tag that you specified. The default value is `LOGIN_WEB`. You should specify this with a relevant tag, like `WITHDRAW` ,`PAYMENT` ,etc. You can specify it using the `EventName` attribute in the config. **Validate the event response** You should validate the event response to make sure it comes from Cotter's server {% content-ref url="/pages/-M2pWffm56vOPZk07RZ7" %} [Validating Cotter's Event Response](/older-api/validating-cotters-event-response) {% endcontent-ref %} ### Skip RedirectURL If you want to handle Cotter's Event Response in a function instead of sending it to your backend `redirect_url`, you can specify ```javascript { ... SkipRedirectURL: true, } ``` When this is true, the [JSON payload](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization#redirecturl) as specified in RedirectURL section will be passed into your [OnSuccess](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization#onsuccess) function. ### **OnBegin** This function will be invoked before the Login process. **You are expected to return a `user_id` at the end of the function**. You will receive the following payload as a parameter to your function **Payload passed into your OnBegin function** ```javascript var payload = { identifier: "+12345678910", identifier_type: "PHONE", device_type: "BROWSER", device_name: "Chrome ..." }; ``` 1. You can do a check against the `identifier` here before the form is submitted. 2. You should get the `user_id` based on the identifier in your backend (or use the identifier if that's what you used). This should be the same as the user id used in the [Required Steps.](/sdk-reference/web/web-sdk-passwordless-login#step-2-creating-a-user) **A. If there is no error:** ```javascript return { userID: "", err: null, } ``` **B. If there is an error:** ```javascript return { userID: "anything", err: "Error message", } ``` Example: ```javascript OnBegin: payload => { if (payload.identifier != "+12345678910") { return { userID: null, err: "Phone Number is not allowed", } } // No error, continue submission var userID = this.getUserIDFromPhone(payload.identifier); return { userID: userID, err: null, }; }, ``` ### **OnSuccess** This function will be called **after** the call to `RedirectURL` is successful. Your function will receive the payload returned from `RedirectURL`. It is recommended to set your sessions or cookies here, and then redirect to another page in your website. For example: ```javascript OnSuccess: payload => { // You can set your own sessions for your website window.localStorage.setItem("access_token", payload.access_token); window.localStorage.setItem("refresh_token", payload.refresh_token); window.location.href = "/dashboard"; }; ``` **OnSuccess when SkipRedirectURL is true** When you set `SkipRedirectURL: true` , `OnSuccess` will instead receive the JSON Event REsponse that was described in RedirectURL section. ### **CountryCode** The default value is `CountryCode: ["+1"];` {% hint style="warning" %} If you specify this, **you have to use an array** even though you only need 1 country code! {% endhint %} ex. with 1 country code ```javascript CountryCode: ["+1"]; ``` ex. with 2 country codes ```javascript CountryCode: ["+62", "+91"]; ``` {% hint style="info" %} Currently, the only available countries are **United States**, **India** and **Indonesia**. Chat us on Intercom if you need other countries, we just need to switch it on. {% endhint %} ### AllowOTPFallback If you set this to true, your users will have the option to use OTP to login/authenticate. You should set OTP Fallback as true in your dashboard under Rules. # Advanced Customization for Pop Up Authentication Prompt The configuration for the Pop Up Prompt is using the configuration for the Login Form, so you can use the [attributes explained in the Login Form.](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization) ```javascript var configAuthRequest = { // Required config ApiKeyID: "", Identifier: "", IdentifierType: "EMAIL", // or PHONE UserID: "", OnSuccess: payload => { console.log(payload); if (payload.approved) { setTimeout(() => { console.log("hel"); }, 3000); // window.location.href = "/"; } } //------ // Allow OTP fallback for Trusted Device AllowOTPFallback: true, // Styling ButtonBackgroundColor: "#000000", ButtonTextColor: "#ffffff", ErrorColor: "#ff0000", AccentColor: "#fff000", ButtonText: "Authenticate", // Change the prompt message AuthRequestText: { title: "Approve this login from your phone", subtitle: "A notification is sent to your trusted device to confirm it's you", image: "https://yourwebsite.com/image.png", titleError: "Something went wrong", subtitleError: "We are unable to confirm it's you, please try again", imageError: "https://yourwebsite.com/image.png", imageSuccess: "https://yourwebsite.com/image.png", switchOTPText: "Authenticate with OTP instead" }, // Event Name in the Event Response EventName: "TRANSACTION", }; ``` Read the specifications for each of these attributes in the [config for Login Form](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization#description). # Getting Access Token and Logged-In User Info {% hint style="warning" %} The following guide only works with [Cotter's NPM package](https://www.npmjs.com/package/cotter) that can be installed using: ```markup yarn add cotter npm i cotter --save ``` This feature is **not supported** on imports using ```markup ``` {% endhint %} ## Get Access Token After the user Authenticates, the SDK automatically stores the Access Token and Refresh Token for your convenience. To get the access token: ```javascript var cotter = new Cotter(API_KEY_ID) cotter.tokenHandler.getAccessToken().then(tok => { console.log(tok) }) ``` This function **automatically refreshes the access token if it's expired.** The returned access token would be in the form of a [CotterAccessToken](https://github.com/cotterapp/cotter-token-js#cotteraccesstoken) object which contains both the string and the decoded token. ## Get Logged-in User After the user Authenticates, the SDK automatically stores the User Information. To get that information: ```javascript var cotter = new Cotter(API_KEY_ID) var user = cotter.getLoggedInUser() console.log(user) ``` ## Log Out To log out and remove these data, do the following: ```javascript var cotter = new Cotter(API_KEY_ID) await cotter.logOut() ``` ## Update Refresh Token (for Custom Claims) `version >= 0.3.24` If you used this [API to get custom claims](/api-reference/oauth-tokens-api/requesting-custom-claims-on-your-access-token), and you received a new `refresh_token` , you can update the refresh token stored in the user's browser by calling this method: ```javascript var cotter = new Cotter(API_KEY_ID) const resp = await cotter.tokenHandler.updateTokensWithRefreshToken(newRefreshTok) console.log(resp) // resp: { "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IlNQQUNFX0pXVF9QVUJMSUM6ODAyOEFBQTMtRUMyRC00QkFBLUJFN0EtN0M4MzU5Q0NCOUY5IiwidHlwIjoiSldUIn0.eyJhZGRyZXNzIjoiSEVsbG9vIiwiYWdlIjoxMjUsImF1ZCI6IjQ3Nzc1YTllLWY1OTktNDk5OS1iNmVhLWY5MDEzMTVhZDMxYiIsImF1dGhlbnRpY2F0aW9uX21ldGhvZCI6Ik9UUCIsImNsaWVudF91c2VyX2lkIjoiZWNhZGJkMmMtNTZmOC00MDc4LWI0NWQtZjE3Nzg2ZWQ0OTllIiwiZXhwIjoxNjA0NjMxMzAyLCJpYXQiOjE2MDQ2Mjc3MDIsImlkZW50aWZpZXIiOiJwdXRyaWthcnVuaWFuQGdtYWlsLmNvbSIsImlzcyI6Imh0dHBzOi8vd3d3LmNvdHRlci5hcHAiLCJqdGkiOiIwZjMzNWI0Yi1mYTk5LTRjOWMtOTIwNS1hNmVlYzA3MjA4YzMiLCJuYW1lIjoiUHV0cmkiLCJzY29wZSI6ImFjY2VzcyIsInN1YiI6ImVjYWRiZDJjLTU2ZjgtNDA3OC1iNDVkLWYxNzc4NmVkNDk5ZSIsInR5cGUiOiJhY2Nlc3NfdG9rZW4ifQ.l5jEBYQnbkPQsahBQSmQhOx4DZhto5UIXVTMm3ODcuYTxQOHdWvc2tmlslvUM6huRO5j4d1VCzh9UFpA4zGqTQ", "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IlNQQUNFX0pXVF9QVUJMSUM6ODAyOEFBQTMtRUMyRC00QkFBLUJFN0EtN0M4MzU5Q0NCOUY5IiwidHlwIjoiSldUIn0.eyJhZGRyZXNzIjoiSEVsbG9vIiwiYWdlIjoxMjUsImF1ZCI6IjQ3Nzc1YTllLWY1OTktNDk5OS1iNmVhLWY5MDEzMTVhZDMxYiIsImF1dGhfdGltZSI6IjE2MDQ2Mjc2OTYiLCJjbGllbnRfdXNlcl9pZCI6ImVjYWRiZDJjLTU2ZjgtNDA3OC1iNDVkLWYxNzc4NmVkNDk5ZSIsImV4cCI6MTYwNDYzMTMwMiwiaWF0IjoxNjA0NjI3NzAyLCJpZGVudGlmaWVyIjoicHV0cmlrYXJ1bmlhbkBnbWFpbC5jb20iLCJpc3MiOiJodHRwczovL3d3dy5jb3R0ZXIuYXBwIiwianRpIjoiMmNmMDE4NTEtNTQyZC00YjZjLTkzZmItZmM5YWUwODQxN2NjIiwibmFtZSI6IlB1dHJpIiwic3ViIjoiZWNhZGJkMmMtNTZmOC00MDc4LWI0NWQtZjE3Nzg2ZWQ0OTllIiwidHlwZSI6ImlkX3Rva2VuIn0.PZmaMOjEySln6ujOLeCwYc8Gn2QX4r6cgvt2DnJPJ67cOEBvOWLBc28wgnGGIFq3PIpIAtkg3z2Sv6PfZSodeQ", "refresh_token": "75063:kisZxVuaTy9LrkzmzXTrmtV1dH7ACYJ951GR99fV86n1CTIOMB", "expires_in": 3600, "token_type": "Bearer", "auth_method": "OTP" } ``` After calling this method**,** it will automatically update all the `access_token`, `id_token` and `refresh_token` with the new value. **This means, when you call `cotter.tokenHandler.getAccessToken()` next, you'll get an access token that has all the custom attributes.** {% hint style="info" %} Access tokens and id tokens that are generated using this refresh token and [subsequently returned refresh token](/api-reference/oauth-tokens-api#refresh-token-rotation) will always have the custom claims. **New Logins** **will not have the custom claims** ​because we don't attach the custom claims to the user itself. {% endhint %} ## OAuth Token Specification {% content-ref url="/pages/-M4HUyse-9aPxMqUoSRy" %} [Cotter's OAuth 2.0 Tokens Specification](/getting-access-token/handling-authentication-with-cotter) {% endcontent-ref %} # Sending Successful Form Submission ![](/files/-MYJKReaM-vsWpZagmk7) If you configured sending successful form submission on the dashboard, and you're using the JS SDK (`cotter` or `cotter-react`), you can add the following to your success function: {% tabs %} {% tab title="`cotter` JS SDK" %} ```javascript import Cotter, { CotterEnum } from 'cotter'; var cotterApiKeyID = "" var cotter = new Cotter(cotterApiKeyID); // πŸ‘ˆ Specify your API KEY ID here var formID = "form_default" cotter .withFormID(formID) // Use customization for form "form_default" .signInWithLink() // Sign In with Magic Link .showPhoneForm() // Send Magic Link via Phone Number .then((resp) => { // == // RUN SUCCESSFUL FORM SUBMISSION // SETUP THAT YOU HAVE IN THE DASHBOARD // == fetch(`${CotterEnum.WorkerURL}/completion/form?form-id=${encodeURIComponent(formID)}`,{ method: "POST", headers: { API_KEY_ID: cotterApiKeyID, "Content-type": "application/json", }, body: JSON.stringify(resp), }).then((_) => { window.location.href = "/protected";// redirect to the protected page }) // == }) .catch(err => { console.log(err) // handle error }); ``` {% endtab %} {% tab title="`cotter-react` React SDK" %} ```jsx import { LoginForm } from "cotter-react"; import { CotterEnum } from 'cotter'; //... const onSuccess = (resp) => { // == // RUN SUCCESSFUL FORM SUBMISSION // SETUP THAT YOU HAVE IN THE DASHBOARD // == fetch(`${CotterEnum.WorkerURL}/completion/form?form-id=${encodeURIComponent(formID)}`,{ method: "POST", headers: { API_KEY_ID: cotterApiKeyID, "Content-type": "application/json", }, body: JSON.stringify(resp), }).then((_) => { window.location.href = "/protected";// redirect to the protected page }) // == } //... console.log(err)} // - A function that runs if the login/signup encountered an error width={340} // - Width & height of the form height={300} // Recommended at least 300x300 formID={"form_default"} /> ``` {% endtab %} {% endtabs %} # FAQ & Troubleshooting ### **Why do I get "Cannot read property 'digest' of undefined"?** Our SDK uses [Web Cryptography API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) to create [SHA-256 digest](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest) for the OAuth 2.0 flow. According to the spec of `crypto.subtle` (from [MDN web docs](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/subtle#Browser_compatibility)), this feature is available only in [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS), in some or all [supporting browsers](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/subtle#Browser_compatibility). In most browsers, secure origins are origins that match at least one of the following (scheme, host, port) patterns: ``` (https, *, *) (wss, *, *) (*, localhost, *) (*, 127/8, *) (*, ::1/128, *) (file, *, β€”) ``` If you're running your application from a secure origin, it's possible that your browser doesn't support the Web Crypto API. For a compatibility table, please check ### **Why does it not show up in incognito?** Chrome and some other browsers doesn't allow cross-origin cookies by default. Try allowing cookies and it should work. We are currently working on an alternative solution, get updates by [joining our Slack channel](https://join.slack.com/t/askcotter/shared_invite/zt-dxzf311g-5Mp3~odZNB2DwYaxIJ1dJA). ### **WebAuthn showing an error \[object Object]** Yes, we are making our error messages better πŸ˜‰. In the meantime, a possible cause is not enabling cross-origin cookie. Make sure that it's enabled and you don't have an ad-blocker. ### I'm seeing "misconfiguration by the owner" ![](/files/-MEjUQCUMLZu76GWl-Uy) Usually this can be caused by one of the problems below: * **You're not using a valid API\_KEY\_ID.** If you're using one of the example CodeSandbox, make sure you paste in your own API key. * **You are accessing a project from a domain that is not listed in Allowed URLs.** Go to your dashboard > Settings > Allowed URLs and check if your current domain is listed. (If you're seeing "\*", then all domains should be allowed). [Read more here](/protecting-your-account/only-allow-your-website-app-to-use-your-api-key). ### Can I style other components like the input label color? Yes, you can extend the styling more than what is available on the dashboard**.** Check out the [styling guide here](/sdk-reference/web/web-sdk-verify-email-phone/styling). ### Can I send the email from my own domain? Not as of now. We are looking for a way to allow you to add CNAME configurations to point your domain to us, but it is not yet available. If you need this feature, make a feature request at [our Slack channel](https://join.slack.com/t/askcotter/shared_invite/zt-dxzf311g-5Mp3~odZNB2DwYaxIJ1dJA). For now, you can change the **From Name,** like this: ![](/files/-MEjW3ONLKp_jbAPHrfc) ### My login form looks cut-off, what is the correct height for the div container? Generally you should follow this: * width: 300px * height: 300px If you're adding Social Login, WhatsApp, or Captcha, make the **height 500px.** ### **My login doesn't want to fill up the div container's width** This can happen if you're using a modal and the modal is not loaded or have `display: none` when you are calling `showEmailForm` or `showPhoneForm` (or `showForm` for older SDK versions). The solution: only show Cotter's form **when the div container and it's parents are loaded with a fixed width and visible display.** ### **I don't receive a verification email, it's automatically showing "Success"** That is expected! We are an identity provider and this means that whenever a user verifies their email with Cotter, **they don't need to re-verify their email again** when logging-in to a website that uses Cotter. This is the same concept as Sign in with Google, you don't need to re-enter your password when signing in to Medium or Asana if you're already logged-in with Google. [Learn more about how our sign-in works](/features/verify-email-phone). ### How do my users Log Out of Cotter? ![Logging Out of Cotter](/files/-MMHT2xmYbB7bZxYXglK) There are 2 things you need to do to log out your users: 1. **Log Out from your app**. When the user logs in, the JS SDK automatically stores the access\_token/refresh\_token such that it's always available for the logged-in user. To log out the user from your app, [call the SDK's Log Out](/sdk-reference/web/getting-access-token-and-logged-in-user-info#log-out) function or remove any stored access\_token/refresh\_token from your website or app. 2. **Log Out from Cotter.** Because Cotter is an Identity Provider like Google, after you log out the user from your app following step 1 above, **your user can log back in to your app without being asked to re-verify their email if they were active in the past 30 days.** If you want the user to be asked to re-verify their email, the user must log out from Cotter (equivalent to logging out of their Google Account). To do this, direct your user to where they can log out from their account. # React Native The easiest way to add Passwordless Login and Email/Phone Number Verification to your React Native app. ## **Complete Guides** #### **Sign in with Device** Allow users to login automatically from a device that they trust. {% content-ref url="/pages/-M2kTuM6W90CT9IpIxHq" %} [Sign In with Device](/sdk-reference/react-native/react-native-sdk-passwordless-login) {% endcontent-ref %} #### Sign in with Email/Phone Number Authenticate users by sending a Magic Link or OTP via email, SMS, or WhatsApp {% content-ref url="/pages/-M1dk\_Rosjlkj52Hq\_6R" %} [Sign In with Email/Phone Number](/sdk-reference/react-native/react-native-sdk-verify-email-phone) {% endcontent-ref %} ## Quickstart Guides {% content-ref url="/pages/-M6Eb1vLZRs1\_0ZAMKrR" %} [React Native – Sign in with Device](/quickstart-guides/react-native-quickstart) {% endcontent-ref %} # Installation Installing Cotter's React Native SDK can be done using yarn or npm. {% hint style="info" %} Make sure you're using `react-native` version **< 0.63** {% endhint %} ## **Install Cotter** Make sure you are using version >= 0.2.0. {% tabs %} {% tab title="yarn" %} ``` yarn add react-native-cotter ``` {% endtab %} {% tab title="npm" %} ``` npm install react-native-cotter --save ``` {% endtab %} {% endtabs %} **Installing Dependencies for bare React Native project** {% tabs %} {% tab title="yarn" %} ``` yarn add react-native-device-info rn-secure-storage react-native-randombytes react-native-camera react-native-svg react-native-securerandom buffer react-native-inappbrowser-reborn react-native-sha256 ``` {% endtab %} {% tab title="npm" %} ``` npm install --save react-native-device-info rn-secure-storage react-native-randombytes react-native-camera react-native-svg react-native-securerandom buffer react-native-inappbrowser-reborn react-native-sha256 ``` {% endtab %} {% endtabs %} ### For iOS CocoaPods ```swift cd ios && pod install && cd .. ``` ### For Android Add the following to your `android/app/build.gradle` ``` android { ... defaultConfig { ... missingDimensionStrategy 'react-native-camera', 'general' multiDexEnabled true } } ``` **Using React Native >= 0.60** πŸŽ‰You're done! Linking the package manually is not required anymore with [Autolinking](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md). ## **(Optional) Additional guides for installation** {% tabs %} {% tab title="Using React Native < 0.60 " %} ```swift react-native link cd ios && pod install && cd .. ``` {% endtab %} {% tab title="Manual Installation" %} Cotter's package doesn't need any manual installation. Cotter is dependent on several packages. Please refer to their docs for manual installation. * [`react-native-inappbrowser-reborn`](https://www.npmjs.com/package/react-native-inappbrowser-reborn#getting-started) * [`react-native-securerandom`](https://www.npmjs.com/package/react-native-securerandom#installation) * [`react-native-sha256`](https://www.npmjs.com/package/react-native-sha256#installation) * [`react-native-permissions`](https://github.com/react-native-community/react-native-permissions) * [`react-native-camera`](https://github.com/react-native-community/react-native-camera) * [`react-native-svg`](https://github.com/react-native-community/react-native-svg) * [`rn-secure-storage`](https://www.npmjs.com/package/rn-secure-storage) * [`react-native-randombytes`](https://www.npmjs.com/package/react-native-randombytes) {% endtab %} {% endtabs %} # Sign In with Device Our React Native SDK offers the easiest way to integrate Cotter's Passwordless Login. 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**](/features/passwordless-login) works. ### What you're building ![Trusted Devices using Cotter's React Native SDK](/files/-M2kXnFknrHlQ5gjoZar) ## Steps 1. [Import Cotter as a dependency](/sdk-reference/react-native/react-native-sdk-passwordless-login#step-1-import-cotter-as-a-dependency) 2. [Set up Cotter in your Project](/sdk-reference/react-native/react-native-sdk-passwordless-login#step-2-set-up-cotter-in-your-project) 3. [Register the current device as a Trusted Device](/sdk-reference/react-native/react-native-sdk-passwordless-login#step-4-register-this-device-as-a-trusted-device) 4. [Authenticate from a Trusted Device and Non-Trusted Device](/sdk-reference/react-native/react-native-sdk-passwordless-login#step-5-authenticate-from-a-trusted-device-and-non-trusted-device) ### Step 1: Import Cotter as a dependency {% hint style="info" %} Make sure you're using `react-native` version **< 0.63** {% endhint %} {% tabs %} {% tab title="yarn" %} ```java yarn add react-native-cotter react-native-device-info rn-secure-storage react-native-randombytes react-native-camera react-native-svg react-native-securerandom buffer react-native-inappbrowser-reborn react-native-sha256 npx pod-install ios ``` {% endtab %} {% tab title="npm" %} ``` npm install --save react-native-cotter react-native-device-info rn-secure-storage react-native-randombytes react-native-camera react-native-svg react-native-securerandom buffer react-native-inappbrowser-reborn react-native-sha256 npx pod-install ios ``` {% endtab %} {% endtabs %} *(Optional) Checkout additional steps* [*for Android, React Native < 0.60, and Manual Installation*](/sdk-reference/react-native/installation)*.* ### Step 2: Set up Cotter in your Project To allow Cotter to display modals, **wrap your root component with `connectCotterWrapper` :** ```javascript import {connectCotterWrapper} from 'react-native-cotter'; class MyApp extends Component { } MyApp = connectCotterWrapper(MyApp); ``` ### Step 3: Register user and trust this device This method `signUpWithDevice` will register the user based on the user's `identifier` to Cotter and then trust the current device. ```javascript import { Cotter } from "react-native-cotter"; class SignUp extends Component { ... register = (identifier) => { // Signup the user and trust this device var cotter = new Cotter(API_KEY_ID); cotter.signUpWithDevice( identifier, // User's email, phone or username this.onSuccess, this.onError, ); }; onSuccess = resp => { alert('Success'); console.log(resp); }; onError = err => { alert('Error'); console.log(err); }; ... } ``` ### Step 4: Authenticate from a Trusted Device and Non-Trusted Device To request an authentication from Cotter's SDK, you would need to call `cotter.signInWithDevice` . **This will automatically detect whether the current device is a Trusted Device or not.** {% tabs %} {% tab title="JavaScript" %} ```javascript // Request authentication var cotter = new Cotter(API_KEY_ID); cotter.signInWithDevice( identifier, // User's email, phone or username this.onSuccess, this.onError, ); ``` {% endtab %} {% tab title="JSON Response" %} ```javascript { // OAuth 2.0 Tokens "oauth_token": { "access_token": "eyJhbGciOiJFUzI1N...", "auth_method": "TRUSTED_DEVICE", "expires_in": 3600, "id_token": "eyJhbGciOiJFUzI...", "refresh_token": "33625:anGsIfvFd...", "token_type": "Bearer" }, // Information about the login request "ID": 2535926, "CreatedAt": "2020-08-01T01:36:24.321921222Z", "DeletedAt": "0001-01-01T00:00:00Z", "UpdatedAt": "2020-08-01T01:36:24.321921425Z", "approved": true, // This login request is approved "client_user_id": "abcdefgh-d15c-466f-aaa3-f029a8e534c3", "event": "LOGIN", "ip": "172.92.5.201", "issuer": "", "location": "San Francisco", "method": "TRUSTED_DEVICE", "new": false, "signature": "L6x8sLHyPTOMCxudw34YTFGCEO4dGvakJl0g9dIDjUp2gaXbD7Yfxo86Dr7OEtHYmSYegSJkwmZjMzDnPvltDQ==", "timestamp": "1596245784", "user_id": "00000000-0000-0000-0000-000000000000" } ``` {% endtab %} {% endtabs %} Cotter's SDK will find the user from `userEmail` , this must be the same as the one used to register the user during sign up. This function returns `oauth_token` , including an `access_token` that you should [validate in your backend](/getting-access-token/verifying-jwt-tokens). You can either: * use this `access_token` to protect all of your API endpoints, or * you can use your own session tokens. You'll need to validate this `access_token` before you generate your session tokens in the backend. {% hint style="info" %} Cotter's SDK automatically stores the OAuth tokens for you. Check out how to [get access tokens and logged-in user information](/sdk-reference/react-native/getting-stored-oauth-tokens-and-user-information). {% endhint %} #### Trusted and Non-Trusted Device 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 an access token. ```java { ... "method": "TRUSTED_DEVICE", "new": false, // Is this a new pending event (should be false). "approved": true // Is this event approved (should be true). "signature": "oonMGCAxp3..." // Signature to make sure this event comes from Cotter's server } ``` You should see a result that the event is **not new**, and that it's **approved**. You'll receive the `oauth_token` because the user is successfully authenticated, and you can pass this to your backend to authorize access for the user. Checkout how to verify the OAuth Tokens from Cotter here: {% content-ref url="/pages/-M4HZPVawEx2QN3qLmnv" %} [Verifying JWT Tokens](/getting-access-token/verifying-jwt-tokens) {% endcontent-ref %} #### Case 2: The current device is NOT a Trusted Device We'll cover this in the next guide: {% content-ref url="/pages/-M2pWufvpIxKQcm3t4RP" %} [Authenticate from a Non-Trusted Device](/sdk-reference/react-native/react-native-sdk-passwordless-login/authenticate-from-a-non-trusted-device) {% endcontent-ref %} ## πŸŽ‰ You're done! # Add Email/Phone Verification {% hint style="info" %} Available from version > `react-native-cotter@0.3.6` {% endhint %} Most of the time, it's required for you to check if the user's identifier (their email or phone number) is valid. With Cotter, you can verify your users via email, SMS, or WhatsApp. ## Step 1: Set Up Deep Linking The verification will follow OAuth's PKCE flow which will open an in-app browser where your user can enter the OTP sent to their email/phone. Pick a unique URL scheme for redirecting the user back to your app after the verification in the in-app browser is successful. For this example, we'll use `myexample://auth_callback` . **Follow the guide under Sign in with Email/Phone –** [**Step 3: Setting up Deep Linking**](/sdk-reference/react-native/react-native-sdk-verify-email-phone#step-3-setup-deep-linking)**,** then come back to this step. ## Step 2: Update your Sign Up Function Make sure you followed the guide for [Sign In with Device](/sdk-reference/react-native/react-native-sdk-passwordless-login). Update your [Sign Up Function that you made on Step 3](/sdk-reference/react-native/react-native-sdk-passwordless-login#step-3-register-user-and-trust-this-device). ### Verifying Before Registering the User **Verify the email/phone number first**, then continue registering the user if verification is successful This will work the following way: 1. The user will be asked to verify their email or phone number 2. If verification successful, we'll create a new User 3. Then, set up the current device as trusted. **If the user already exists but doesn't have a Trusted Device** set up (for example from logging-in to your website): 1. The user will be asked to verify their email or phone number 2. Then if verification successful, set up the current device as trusted. ```javascript import { Cotter } from "react-native-cotter"; class SignUp extends Component { ... // Remove your `register` function, and update to the following // signupOrLogin function. // This function handles both Sign Up and Login const signupOrLogin = async () => { let cotter = new Cotter(API_KEY_ID); try { // Fetch user using the User API // identifier = user's email const user = await cotter.getUserByIdentifier(identifier); console.log(user); if (validUUID(user.ID) && user.enrolled.includes('TRUSTED_DEVICE')) { // ======================== // Existing User // ======================== // A) User already have a trusted device // proceed with SignInWithDevice cotter.signInWithDevice( identifier, resp => console.log('Success', resp), errs => console.log('Error', errs), ); } else { // =========================================================== // New User OR Existing but No Trusted Device // =========================================================== // B) User doesn't exists OR exists doesn't have a trusted device // 1️⃣ Verify Email await cotter.signInWithEmailLink( 'myexample://auth_callback', resp => { // 2️⃣ Proceed with registering this device as a trusted device registerDeviceAsTrusted(); }, err => alert('Error', err), {email: identifier}, ); } } catch (e) { alert('Error', err); } }; const registerDeviceAsTrusted = async () => { let cotter = new Cotter(API_KEY_ID); const user = await cotter.getLoggedInUser(); user.registerDevice( resp => console.log('Success', resp), err => console.log('Error', err), ); }; ... } ``` # Authenticate from a Non-Trusted Device ## Steps There are 2 steps in authenticating a Non-Trusted Device 1. [Make a request](/sdk-reference/android/older-sdk-version/android-sdk/old-authenticate-from-a-non-trusted-device#step-1-making-an-authentication-request) from the Non-Trusted Device and wait for approval. The SDK will automatically show a prompt asking the user to approve this request from the Trusted Device. 2. [Approve the request](/sdk-reference/android/older-sdk-version/android-sdk/old-authenticate-from-a-non-trusted-device#step-2-how-to-approve-a-pending-request-from-a-trusted-device) from a Trusted Device. The user should tap a button to **check if there's a login request.** They can then **approve or reject** the login request. 3. When the login request is approved, the Non-Trusted Device will receive `oauth_tokens` . You should validate these tokens in your backend. ## Step 1: Make an Authentication Request ![Requesting Login from a Non-Trusted Device](/files/-MDc9F-J-GWdDSrrfo-z) Same as how it works with [Authenticating from a Trusted Device](/sdk-reference/react-native/react-native-sdk-passwordless-login#step-6-authenticate-from-a-trusted-device-or-non-trusted-device), to authenticate a device, call `cotter.signInWithDevice` . **This will automatically detect whether the current device is a Trusted Device or not.** ```java // 1️⃣ Request trusted device authentication var cotter = new Cotter(API_KEY_ID); cotter.signInWithDevice( identifier, // User's email, phone or username this.onRequestSuccess, this.onRequestError, ); ``` When an Authentication Event is requested using method `TRUSTED_DEVICE`, there are 2 possible cases: ### Case 1: The current device is a Trusted Device You will be automatically approved if the request is coming from a Trusted Device. This is covered in [Authenticate from a Trusted Device](/sdk-reference/react-native/react-native-sdk-passwordless-login#case-1-the-current-device-is-a-trusted-device). ### Case 2: The current device is NOT a Trusted Device If the current device is **not** a Trusted Device, then it will create a **pending event.** This pending event will need to be **approved by a Trusted Device**. ## Step 2: How to approve a pending request from a Trusted Device ![Press a button to approve a login request from the Trusted Device](/files/-MDc9P7EfBfYlPg6CrWG) To check if there's a pending event for this user, you can call the `getNewEvent` method from a Trusted Device. ```javascript approveLogin = async () => { let cotter = new Cotter(API_KEY_ID); try { let user = await cotter.getLoggedInUser(); await user.checkNewSignInRequest(); } catch (err) { console.log(err); } } ...