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.

What you're building

Cotter's Embeddable Login Form using the JS SDK

Try it out

Quickly try out how it works in our Hello World Example! πŸŽ‰

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

Steps for Cotter's Web SDK
  1. ​Setup Cotter with your API_KEY_ID and some config

  2. ​Show Cotter form​

  3. ​Send the Payload 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.

<script
src="https://js.cotter.app/lib/cotter.js"
type="text/javascript"
></script>

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.

<script>
var cotter = new Cotter(config);
</script>

Configuration

Here's a basic configuration example:

var config = {
ApiKeyID: "<your-API-KEY-ID>",
// Type of identity your want to collect: EMAIL or PHONE
Type: "PHONE",
// div id of the container for Cotter Form
ContainerID: "cotter-container-signup",
// the JSON key for the phone number or email to be posted to RedirectURL
// Read more on RedirectURL JSON Object below
IdentifierField: "phone",
// The payload will be the user's information and a signature from Cotter
OnSuccess: payload => {
// payload is Cotter's token containing user information
console.log("Cotter User Information", payload);
// Send Cotter's token to your server's signup or login endpoint
// you should validate the payload from Cotter in your server.
// Read: Validating Cotter's Identity Token
// for example, this loginOrSignUpInMyServer endpoint should
// validate the payload, then either register a user if it's
// a new user, or log them in if it's an existing user.
loginOrSignUpInMyServer(payload); // πŸ‘ˆ You need to define this function
},
​
// Read and handle any errors in this function
OnError: (error) => {
console.log(error);
},
};

Adding more fields

You can also add more fields, customize the styles, and intercept the authentication request before it's sent. Check out how to Customize the Form.

Send Code via WhatsApp

Instead of using SMS, you can also send the verification code via WhatsApp.​

Step 2: Show Cotter Form

To show the cotter form,

1. Add the <div> container.

Put a <div> with the id you specified above as ContainerID inside your page. For example, if your "ContainerID": "cotter-container-signup", put this in your html:

<div
id="cotter-container-signup"
style="width: 300px; height: 200px;"
></div>

2. Show the form

<script>
cotter.showForm();
</script>

What we have so far

index.html
<script
src="https://js.cotter.app/lib/cotter.js"
type="text/javascript"
></script>
​
<div
id="cotter-container-signup"
style="width: 300px; height: 200px;"
></div>
​
<script>
var config = {
ApiKeyID: "API_KEY_ID", // πŸ‘ˆ You need to add your API KEY ID
Type: "PHONE", // EMAIL or PHONE
ContainerID: "cotter-container-signup",
IdentifierField: "phone",
OnSuccess: payload => {
console.log("Cotter User Information", payload);
loginInMyServer(payload); // πŸ‘ˆ You need to define this function
},
OnError: (error) => {
console.log(error);
}
};
var cotter = new Cotter(config);
cotter.showForm();
</script>

Step 3: Sending the Payload to your Backend Server

You MUST set a function called OnSuccess to receive Cotter's a JSON object containing the user's information. For example:

OnSuccess: payload => {
console.log("Cotter User Information", payload);
loginInMyServer(payload);
}
​
// Example function to send to server
async function loginInMyServer(payload) {
fetch("/user/login", {
method: "POST",
body: JSON.stringify(payload),
headers: {
Accept: "application/json",
"Content-Type": "application/json"
}
})
.then(response => {
// HANDLE response from your server
})
.catch(err => {
console.log(err);
});
}

The payload inside the OnSuccess function that was sent to your server is a JSON Object with the following format:

{
"token": {
"identifier": "+12345678910",
"identifier_type": "PHONE",
"receiver": "<your API_KEY_ID>",
"expire_at": "1582679175", // Unix timestamp
"signature": "7en+KvbLpMkA7Z93K5y3a12tDo2x3n..." //Signature
},
[IdentifierField]: "+12345678910"
}

You should verify the signature in the token to ensure this is valid and it comes from Cotter's server.

Register or Login your user to your Database

Let's take a look again at the JSON Object given to your RedirectURL

{
"token": { ... },
[IdentifierField]: "+12345678910"
}

The IdentifierField will be replaced with the value you put in the config. For example if you put "IdentifierField": "phone" it will look like:

{
"token": { ... },
"phone": "+12345678910"
}

You can then use this information, along with verifying the signature, to Register or Login the user.

Register your User to Cotter

To use Trusted Devices from Cotter to authenticate your user, you need to register your user to Cotter too. Right after you validate the token, register your user to Cotter using the user_id you created in your server (you can also just use the email or phone number )

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

Request
Response
Request
curl -XPOST \
-H 'API_KEY_ID: <your API KEY ID>' \
-H 'API_SECRET_KEY: <your API SECRET KEY>' \
-H "Content-Type: application/json" \
-d '{"client_user_id": "xyzABC12345", "identifiers": ["[email protected]", "+123456678910"]}' \
'https://www.cotter.app/api/v0/user/create'
Response
{
"ID": "6d24ed5b-4a87-4e7f-81e6-37861f8048ce",
"created_at": "2020-04-06T19:16:27.555304-07:00",
"update_at": "2020-04-06T19:16:27.555304-07:00",
"default_method": null,
"deleted_at": null,
"enrolled": [],
"client_user_id": "xyzABC12345", // Your client user id
"identifiers": [ // Identifiers for this user
"+123456678910"
],
"issuer": "<your API-KEY-ID>" // Your api key id
}

Check out Create a User API Reference for full Description

Validating Cotter's Token

Checkout how to verify the signature in Cotter's token here:

πŸŽ‰ You're done!