Overview

Swoop allows you to add a passwordless login option to your website or web application (hereafter just referred to as “your website”). Instead of using a password, your users will authenticate using email. This process starts in Swoop’s modal that you trigger when a user wants to login in using Swoop.

You’ll notice there are two options: sending an email and receiving an email. These are the two methods Swoop provides for logging in with email.

You might be familiar with logging in by receiving an email from sites like Medium. You enter your email address and are sent a “magic link”. By clicking the link you are taken to the site and immediately logged into your account. 

Sending an email works a bit differently. Using either a mailto link or deep link into a web mail client of the user’s choice, Swoop opens a pre-composed email addressed to a unique, one-time-use email address at SwoopLogin.com. The user then sends the email. When it is received by Swoop, we use DKIM and SPF to verify the identity of the sender. We then log the user in through the Swoop interactive login modal.

Installation

To start using Swoop you’ll need to do two things. One, add the Swoop modal to your website. And two, add functionality to your website so it can process login requests coming from Swoop.

Swoop Modal

To add the Swoop interactive modal to your website you need to include the following Javascript on your website:

<script src="https://app.swoopnow.com/swoop.js"></script>

Swoop modal is implemented via an iframe and the code you just added creates that iframe. If you have security concerns about adding third-party Javascript to your website, you are welcome to download the “swoop.js” file and host it yourself. If you audit the code, you’ll see that it really is just adding an iframe (the Swoop modal) to your page and all the serious stuff happens within that iframe.

Once you have that Javascript on your website, you need initialize the Swoop modal by identifying yourself. You do this like so using your Website ID (which will start with “wb_”), which is found in the Swoop dashboard:

<script>
  Swoop.init('wb_your_website_id');
</script>

You can just put this code in a script block somewhere on your website after the inclusion of the “swoop.js” file.

Finally, when you want the Swoop modal to appear, you trigger it with the following JavaScript:

<script>
 Swoop.open('login');
</script>

Often this is tied to the onclick event of a button like so:

<button>Log In</button>

Login Requests

The other piece of adding Swoop to your website is accepting and processing the Swoop login requests. In the Swoop dashboard, you specify a “login endpoint”. When a user is logging in, we’ll redirect them to the login endpoint you specify and add a token (a random 16 digit hex string) to the request under the URL parameter ‘id’.

When your website receives that redirect, it needs to make an API call to Swoop to request the identity of the user who is attempting to login. You do this by making a GET request to the Swoop API endpoint (https://app.swoopnow.com/api/inbound_emails) with the ID you’re looking up as and additional path. I.e. if the ID I received in the redirect was “4f6ca107f981456c5a2b159af293944c”, I’d make my request to “https://app.swoopnow.com/api/inbound_emails/4f6ca107f981456c5a2b159af293944c”.

If that token corresponds to an actual user, you will receive a response with a status code of 400 and a plain text body containing the email address of the user logging in. Otherwise, the response will have a status code of 404 and no body.

Once you have the email address of the user, you can proceed with your normal login process and move the user into a logged in state.