Quick Start

Swoop offers a client-side Javascript library that handled the entire OAuth2 + PKCE authentication flow for you. While Swoop has many advanced featured, this guide will show you the basics and how to get started using only a few lines of Javascript

Before you begin, make sure you have signed up for Swoop (It's free)

Creating A New Swoop App

Here are the steps to creating an app

1. Head to the Swoop Dashboard
2. Click Add New App
3. Give your app a name and enter your app's URL (localhost is fine for testing)
4. Click Add It
5. Once created, click the Credentials menu item and take note of the Client ID. It will be needed in the next steps

Add The Swoop SDK To Your Website

You can add the Swoop SDK anywhere in your site's source code. Make sure it is marked as async and defer.

<script src="https://cdn.jsdelivr.net/npm/@swoop-password-free/swoop/dist/swoop.js" async defer></script>

Add Your App's Client ID

Add the following meta tag to your site's head element with your app's Client ID

<meta name="swoop-client-id" content="[YOUR_SWOOP_APP_CLIENT_ID]">

Add The Swoop Smart Button

Swoop can be added in a number of ways. You can choose to connect it to any button or link you want (detailed here), however the easiest way is to use our Smart Button. Simply add a div anywhere on your site with the class swoop-button.

<div class="swoop-button"></div>

Connect Swoop To Your Own Button

If you would like more control of your user experience, you can hook Swoop up to any button, link, or JS event in you app. Here is a simple line that calls the swoop.in() function when clicking on a button.

<button onclick="swoop.in();">Login With Email</button>

Get The User Information

After the user validates their email with Swoop, you can access their information with a callback function. By default, the callback function is called swoopOnSuccess and it takes one parameter called user.

function swoopOnSuccess(user) {
  console.log(user);
  // user.id_token
  // user.email
  // user.uid
}

📘

Important

While the user is "logged in" on the client side, you still need to create a session for them on your server. It's considered a best practice to send user.id_token to your server to validate it against your Swoop Secret.

Sign Out

Swoop remembers the last email your user signed in to your site with and uses it in the Smart Button to provide a visual cue to them which email they used on your site. You can clear this by calling the swoop.out function.

function logout() {
  swoop.out();
}