Trying your Flow

The basics to getting started with Flow

We've designed Flow to be as simple as possible for you to try out on your website. To get started, visit the Flow dashboard, select the template you want to use, and click on the "Integration" button.

Whitelisting Domains

Before you can use Flow, you need to specify which domains are allowed to run embed your Flow integration. Open the "Domain Whitelist" settings tab, and add an entry for each domain you want to use Flow on.

For example, if I wanted to embed Flow on fintechly.co and staging.fintechly.co, my entries would be:

  • https://fintechly.co
  • https://staging.fintechly.co

We don't support wildcards, so you need to define each entry separately. To keep your users secure, we only support HTTPS.

If you want to try Flow out first in your development environment, we recommend using [ngrok][ngrok] to create a free temporary access point for your local server with HTTPS enabled.

Your Flow Code Snippet

Once you've configured which domains may embed your Flow, open the "Integration Code" tab and copy the code snippet. This code snippet includes:

  • A <script> tag that loads Cognito's Flow.js library
  • Your publishable API key
  • The ID associated with your Flow template

Paste this code snippet into the part of your application where your customers will be using Flow. The customerReference and email fields should be customized per user. We'll return to those later in the guide.

Embedding Flow

The simplest possible code for trying out your Flow would look like this:

<script src="https://cdn.cognitohq.com/flow.js"></script>

<script type="text/javascript">
  const flow = new Flow({
    publishableKey: "live_publishable_key_e61c93ca932b97a1431cc19b1c6cd1fc",
    templateId: "flwtmp_aec2rrgcz5NyC1",
    user: {
      customerReference: currentUser.id
    }
  });
</script>

where currentUser.id should be the unique internal identifier your application uses to track your user. In most applications, this should be the id column on your users table. For additional context on why we require this, read the customer reference section.

The code above initializes Flow. Now, to launch flow, you need to bind the open() function to a button in your UI. For example, with plain javascript this might look like:

<button id="launch-flow">Verify my Identity</button>

<script type="text/javascript">
  document
    .querySelector("#launch-flow")
    .addEventListener("click", () => flow.open());
</script>

and if you're using React, your code might look like this:

<button onClick={() => flow.open()}>Verify my Identity</button>

Customer References

At the center of Flow is the mandatory "Customer Reference" field, which we expect will be a unique and persistent identifier for your customer, ideally something like the id field on your users table. Some of the benefits of this approach include:

  • You don't have to hit Cognito's servers at all before your customer starts a Flow session
  • You don't have to store any identifiers from Cognito on your users table

Flow also intelligently handles sessions being started with the same customer reference multiple times. If your customer starts a Flow session, closes the page, reopens it, and reopens your Flow integration, their session will resume from where they left off. Likewise, if your customer has completed their Flow session in the past (by either failing verification or passing), we will not serve serve them another session unless you've manually authorized another attempt from our dashboard.

On top of this, we index the customer references you send us, so in the future our APIs will allow you to lookup users in our API using your internal id.

With all of this said, if you still do not want to expose your internal id to Cognito directly, you can always symmetrically encrypt the identifier with a secret key that only your servers know. This will keep the id private, and when you're handling our webhooks you can use the same key to decrypt the customer reference. If you choose to do this, just remember you need to sign the encrypted identifier, not the original id.

Supplementing email

The Flow client accepts email as an optional additional parameter, like so:

<script src="https://cdn.cognitohq.com/flow.js"></script>

<script type="text/javascript">
  const flow = new Flow({
    publishableKey: "live_publishable_key_11111111111111111111111111111111",
    templateId: "flwtmp_11111111111111",
    user: {
      customerReference: currentUser.id,
      email: currentUser.email
    }
  });
</script>

While the field is optional, we highly recommend providing it. Flow will include the user's email in the Flow session and perform a number of anti-fraud related checks, including:

  • Checking if the email is registered with 20 different popular social networks
  • Inferring how long the email has been in use, by checking for its presence in past data breaches
  • Checking for signs of fraud and abuse, like whether the email is disposable, recently registered, or not configured to accept email

That's it! You should now be able to click your button and use the Flow that you designed.

If your Flow doesn't launch, you can trouble shoot by: