GUIDES

Feature Announcement: Users API

Brian Yam
,
Head of Marketing
September 3, 2021
,
4
minutes to read
Table of Contents
Get the best SaaS integration resources right in your inbox.
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
Should you build a Zapier connector? <br>Read Guide

If you’ve been with us for a while, you’ll know that we’ve been busy pumping out new pre-built integrations, so you won’t need to worry about the complexities of messy 3rd party API docs, building authentication, and designing and building the end-user configuration experience.

However, behind the scenes, we’ve been working on a suite of developer features that will make Paragon even more extensible as a platform!

Today, we’re officially rolling the first major user management upgrade - the Users API!

While we’ve made it incredibly easy to build and deploy integrations to your end-users on Paragon’s user interface, the Users API will provide a programmatic way to manage your Connected Users and their integrations, directly from your application logic.

Let’s see what this means for you as a developer building on Paragon.

Table of Contents:

  • Managing integration and workflow states
  • Passing through custom metadata
  • Headless implementation

Viewing and Managing Integration States

Let’s start with the basics - managing integration states for your end-users.

Historically, your end-users enable integrations and workflows through the Connect Portal for each integration. While this is a great end-user experience, the one downside from a developer experience standpoint is that there hasn’t been an easy way for you to view or manage those integrations on their behalf.

A few situations where this becomes a challenge:

  • If one of your end-users downgrade or cancel their subscription (although hopefully that never happens), you don’t want the integration to remain up and running if they should no longer have access to the integration.
  • If you’re investigating a potential issue with an end-user’s instance that relates to an integration, you may want to not only view the states of their integrations, but also have the ability to disable specific integration workflows while you work on resolving the issue.

Viewing integration states

With a simple paragon.getUser() call, you can instantly return all the details of a specific end-user, including their userID, auth status, and the integrations they’ve enabled.

paragon.setUserMetadata({ Name: user.fullName, Email: user.email, Company: user.company, apikey: user.apiKey });

So for any account that might be experiencing issues with workflows not triggering, this is the first place you can look.

Disabling integrations and workflows

If your end-users decide to downgrade or unsubscribe from your service for some absurd reason, you’ll want to make sure their integrations are no longer enabled. It’s pay to play after all.

Of course, you could try and ask them nicely to go in and disable their integration, but you’ll likely be left on read.

Luckily, through the Users API or the Paragon SDK, you can now now easily disconnect any integration for a specified, authenticated user.

{{insert SDK/API snippets}}

Pretty straightforward right?

Now that we have the basics covered, it’s time to get into one of the most powerful features of the Users API.

Passing custom metadata

Prior to the Users API, the only identifiable attribute an end-user had in Paragon was the Paragon User ID.

This mean that it required manual work to identify which of your customers a user ID was associated with, and it also prevented you from appending any additional properties to users.

With our PATCH endpoint, we’ve unlocked the ability for you to pass and associate any custom metadata properties for a given user, which can then be accessed through the Paragon SDK.

paragon.setUserMetadata

While any string can be passed through as metadata, the 2 core use cases are:

  1. Appending additional identifiers to each authenticated user
  2. Passing unique API keys for each of your customers

Additional Identifiers

This is pretty straightforward, so we’ll run through it.

eAssociating external identifiers and attributes such as a user’s email address, name, company name will enable you to much more easily filter for the executions and integration states for any customer.

This essentially turns Paragon into a CRM (database of your customers) that contains every end-user’s integration data.

In a practical example, if someone on your support team comes to you and says ‘Hey, John from BookFace said their integration isn’t working’, you can now easily query his email address and return all the executions related to his authenticated account.

API Keys

An arguably more requested use case is to associate API keys for each end-user.

Say you want to interact with your own API within a Paragon workflow, but each of your customers have a specific and unique API key that is required to modify states and data in your application.

Previously, you would’ve had to securely surface an endpoint on your API to pull that key.

Now, it’s super easy to set that API Key as a metadata field upon authentication or after the fact, and simply reference that API Key in any workflow to authenticate a user back into your API.

There are two ways to go about associating metadata with your end-users.

paragon.setUserMetadata({    Name: user.fullName,    Email: user.email, Company: user.company, apikey: user.apiKey});

What about the front end?

While the Users API is perfect for developers, it’s important that your customer-facing teams (usually support/success) have the ability to manage your users’ integrations as well.

That’s why this month, we’ll be launching the front-end counterpart of the Users API - stay tuned!

Never miss a thing
Subscribe for more content!

Ready to get started?

Book a demo or start building with Paragon today.