Multi-Configuration allows you to use one connected account authorization (1 credential) to set up multiple configurations of User Settings or Workflow enablements for your users.
For example, if your Google Drive integration might require you to set up different workflows for different folders that your user wants to watch, Multi-Configuration can provide a separate “instance” of the Connect Portal to show for each of those folder configurations.
Configurations
A Configuration is a set of User Settings and Workflow Enablements associated with one connected account (credential), as shown here:
In the above example, User A with Google Drive Credential A can have N configurations associated with that credential.
- Different sets of Workflows can be enabled / disabled for each configuration.
- Different User Settings can be used for each configuration.
- Configuration-specific Metadata can be set and used within Workflows and the SDK.
- Credentials and Configurations can be associated with an External ID (an ID that you provide).
- Our customer can optionally provide us with an External ID to create a credential or configuration.
- An External ID which can be used to reference a Credential / Configuration(s) in place of a UUID, in the following format:
ext:[External ID]
- For example, if the configuration is created with
externalId: "Team A", it can be addressed in the Paragon User Token as configuration:ext:Team A.
Usage
Creating and managing configurations
To create a new configuration, call createConfiguration with a credentialId to attach the configuration to and an optional externalId to reference this configuration in the API.
const config = await paragon.createConfiguration({
// The credential to create this configuration from
credentialId: "...",
// An external ID that can be used to reference this configuration from the API
externalId: "Team A"
});
// -> { id: "", credentialId: "", settings: {}, configuredWorkflows: {} }
createConfiguration call will return a Promise that resolves with the saved configuration object.
After creating a configuration, it will be included in the getUser() response under each integration, in both the allConfigurations array and within the configurations property of each credential object.
paragon.getUser();
// -> { jira: { allCredentials: [{ configurations }], allConfigurations: [] } }
destroyConfiguration:
// Destroy a configuration of this credential
await paragon.destroyConfiguration({ id: "ext:Team A", credentialId: "..." });
Presenting the Connect Portal
After creating a configuration, you can present a Connect Portal by passing selectedConfigurationId. You can pass a configuration UUID or the external ID prefixed with ext:to reference the configuration.
// Open Connect Portal of this configuration
paragon.connect("jira", {
selectedConfigurationId: "ext:Team A"
});
// Manage Headless workflow enablements for this configuration
await paragon.enableWorkflow("workflow-id", {
selectedConfigurationId: config.id
});
await paragon.disableWorkflow("workflow-id", {
selectedConfigurationId: config.id
});
Note: All credentials have a default Configuration included, which will be used if the configuration does not exist or if selectedConfigurationId is undefined.
Calling the API
You can use selectedConfigurationId as an option for SDK calls and X-Paragon-Configuration-Idfor API calls.
// Send an App Event for this configuration only
await paragon.event("workflow-id", {
selectedConfigurationId: config.id
});
POST /sdk/events
X-Paragon-Credential: a1304037-d994-40ef-894a-8d6c55f65f7c
X-Paragon-Configuration-Id: ext:Team A
Access Control
If your Connected Users represent accounts, organizations, or some other group of users in your platform, then you may want to control the visibility and permissions for your configurations within a Connected User.
You can do this by adding a custom claim on the Paragon User Token (JWT) that is passed for an authenticated user in your platform.
This claim is called urn:useparagon:connect:permissions and is structured as an object with keys of JWT Scopes and values of JWT Permissions.
// Admin has access to all integrations
{
"sub": "<Paragon User ID>",
"urn:useparagon:connect:permissions": {
"integration:*": true
}
}
// Member of Team A only
{
"sub": "<Paragon User ID>",
"urn:useparagon:connect:permissions": {
"integration:*": true,
"integration:slack": {
// Applies to all teams
"credential:*": {
"permissions": [
"events"
]
// Applies to all Slack configurations with ext ID of
// "Team A", for all Slack accounts
"configuration:ext:Team A": [
"config:write",
"settings:write"
]
}
},
"integration:custom.test": false,
"integration:hubspot": {
"credential:*": [
"config:write"
]
}
}
}
JWT Scopes
The following scopes can be used to designate permissions as listed above. These scopes are ordered from least specific to most specific.
Permissions designated at more specific scopes will override those inherited from less specific scopes.
| Scope | Description |
|---|
| integration:* | All integrations |
| integration:[name] | An integration matching a name of [name] (as passed to paragon.connect ) |
| credential:* | All credentials belonging to an integration |
| credential:[uuid] | All credentials matching an ID of [uuid] |
| configuration:* | All configurations belonging to a credential |
| configuration:ext:[id] | All configurations matching an External ID of [id] |
JWT Permissions
The following permissions can be used to configure API capabilities for a Paragon User Token. These permissions can apply to any of the scopes listed in JWT Scopes.
Permissions must be specified as an array, or as a Boolean interpreted as true = Allow All, false = Deny All.
| Permission | Description |
|---|
| credential:write | Connect a new credential, reconnect an existing credential, or disconnect an existing credential |
| config:write | Create, modify, or destroy a configuration |
| settings:read | Read User Settings and Workflow Enablement |
| settings:write | Write and read User Settings and Workflow Enablements |
| metadata:read | Read User Metadata |
| metadata:write | Write and read User Metadata |
| proxy-api | Send requests to the Proxy API |
| events | Send App Events |
| workflows | Send Workflow Request triggers |
