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 [.inline-code-highlight]paragon.getUser()[.inline-code-highlight] call, you can instantly return all the details of a specific end-user, including their userID, auth status, and the integrations they’ve enabled.
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.
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:
- Appending additional identifiers to each authenticated user
- Passing unique API keys for each of your customers
Additional Identifiers
This is pretty straightforward, so we’ll run through it.
Associating 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.
1. Associate the metadata as part of your paragon.authenticate() call
2. Supply the metadata from your product separately after the authenticate call
What's next
We will be releasing a lot of new features that rely on your ability to associate metadata to your Connected Users, such as leveraging metadata to set integration permissions for users, so stay tuned for future updates!
