JWT Permissions

If your Connected Users represent accounts, organizations, or some other group of users in your platform, then you may want to control the permissions of the credentials and configurations within that user to only the set that an authenticated user of your application should have access to. By default, a Paragon User Token grants access to all credentials and configurations within a Connected User (identified by the sub field in the JWT).

Diagram illustrating org- vs. user-level tokens

You can restrict access to specific credentials and configurations by adding an additional claim on the Paragon User Token (JWT) that is passed for an authenticated user in your platform. You can also use JWT Permissions to prevent certain types of API calls from being made using a given token, for example: Proxy API calls, App Events, Workflow triggers, or ActionKit requests.

Usage

The claim for JWT Permissions is called urn:useparagon:connect:permissions and is structured as an object with keys of Scopes (i.e. what to scope a group of permissions/rules to) and values of Permissions (i.e. visibility of specific credentials or configurations and the types of operations that are allowed). Here are some examples of token types that are expressible with JWT Permissions:

{
  "sub": "<Paragon User ID>",
  "urn:useparagon:connect:permissions": {
    "integration:*": true
  }
}

{
  "sub": "<Paragon User ID>",
  "urn:useparagon:connect:permissions": {
    "integration:gmail": {
      "credential:abf961e3-12ec-40fe-8aa9-caa5ab162a6a": true
    }
  }
}

{
  "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 external 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"
      ]
    }
  }
}

{
  "sub": "<Paragon User ID>",
  "urn:useparagon:connect:permissions": {
    "permissions": [
      "actionkit"
    ],
    "integration:salesforce": {
      "credential:*": true
    },
    "integration:hubspot": {
      "credential:*": true
    }
  }
}

Claims passed in the JWT are not persisted or saved in any way. They are only used and evaluated for the current API request and should be included with every token that requires permissions control.

JWT Scopes

The following scopes can be used to assign permissions and rules. 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]

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 above. 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
actionkit	Send requests to the ActionKit API

​Usage

​JWT Scopes

​JWT Permissions

Usage

JWT Scopes

JWT Permissions