Introduction
The Users API allows you to query and modify the state of your Connected Users and their integrations. The API includes REST endpoints (and matching SDK functions) for identifying what integrations your user has enabled, disconnecting integrations, and disabling workflows. The API also allows your application to associate metadata with a Connected User.✨ User Metadata is included in the Pro Plan and above. Contact us to schedule a demo of User Metadata or upgrade your account.
When to use the Users API
The Users API can be used for integration usage analysis or maintenance of Connected Users. For example, using the API methods, you can…- Automatically disconnect integrations when a user deletes or downgrades their account in your application
- Enrich your Connected Users’ profile information with email, name, and other metadata
- Check if a user has enabled a certain integration and view account connection status
Authorization
Requests to the Users API are authorized with a Bearer-typeAuthorization
header using a Paragon User Token:
paragon.authenticate
:
Examples
Associate Connected User with metadata
You can associate your user with metadata by including it in your existing SDK call toparagon.authenticate
, as an additional parameter:
Note:
Name
and Email
are special parameters that you can view within the Connected Users Dashboard. They are also case-sensitive.Using Metadata in Workflows
Metadata properties are available for use in workflows in the variable menu of the Workflow Editor. To select a metadata property in a workflow, you’ll first need to set a sample metadata object. From any workflow, click the Options menu in the top navigation and select Set User Metadata:.png?fit=max&auto=format&n=VPMcg_H0p5RWAFJc&q=85&s=c2c6a463f7d538226fe80291fcc73a12)
.png?fit=max&auto=format&n=VPMcg_H0p5RWAFJc&q=85&s=8d2279e8e1777801d88c3105029b2a9d)
Get Connected User info and integration state
You can access Connected User info (including any associated metadata) usingparagon.getUser
or with the REST API.
Validating account status with the credentialStatus
property
If a previously connected account is unreachable (e.g. your user revokes access from the integration), the Connect Portal will show a warning and prompt your user to reconnect their account:

credentialStatus
property. For example:
credentialStatus
is not "VALID"
. You can initiate a reconnection flow with the same function used to start a connection flow: .installIntegration(integrationType: string, installOptions?: InstallOptions) -> Promise<IntegrationInstallEvent>.
Disconnecting integrations
Integrations can be disconnected usingparagon.uninstallIntegration
or with the REST API.
When an integration is disconnected, workflows for that integration will stop running for the authenticated user and any saved User Settings will be cleared.