Customizing the JWT

At a minimum, the JWT (JSON Web Token) passed from your application to the Pandium In-App Marketplace must offer a unique identity for the user accessing the marketplace. Nevertheless, the token’s functionalities go beyond simply logging a user into Pandium.

By customizing the JWT, you can configure various options, like displaying specific integrations to certain users, defining user groups, and executing other actions tailored to your requirements.

Note: The In-App Marketplace and related features are not included in the Pandium Lite offering.

Customizing Marketplace Views

When configuring your marketplace, you might need distinct views based on user and app groupings.

This customization can be seamlessly achieved by manipulating a JWT. By specifically identifying users and apps through email and ID within the xti (extra tenant information) field in the JWT, and following predefined rules set by Pandium to support these rules, you can unlock several possibilities.

Below are a few relevant use cases for changing the marketplace view:

Displaying Multiple App Types to a Single User

If you wish to selectively present certain integrations to a user, you can refer to the app ID in the JWT. Specify a list, for example, using a field like ‘hidden_integrations,’ and those apps will not be visible to specific user(s).

Showing Different Marketplaces By a User Group

Similarly, you can define a group, such as. ‘user_group’ or ‘user_tier’ in the xti field. List the apps you want to display for that particular group.

Managing Integration Installs Based on User Groups

Once again, within the same xti field, you can define a user group and introduce parameters like ‘allowed_installs.’ This feature can limit the number of apps a user is permitted to install. For additional use cases, please reach out to your Technical Account Manager so that we can collaborate on supporting these functionalities.

Note: The Marketplace and related features are not included in the Pandium Lite offering.

Linking Legacy Integrations in the In-App Marketplace

If you have existing apps linked to existing "legacy" integrations and wish to showcase them in the embedded marketplace, enabling customers to link out to installed instances, follow these steps:

1. Create an External Integration - find instructions here.

2. In the JWT, under the external integration ID field represented by ili, insert the value passed into the JWT. If the customer has the integration installed, it will be visible in the marketplace; if not, it won't show, and the app will appear normally.

3. In the external integration URL field on an external integration, paste the URL where the integration lives in your system.

The JWT payload is where your application encodes custom information or claims about your user.

Refer to table below for a list and descriptions of the claims your JWT should contain:

JWT Payload:

The JWT payload is where your application will encode the custom pieces of information, or claims, about your user.

The table below provides a list and descriptions of the claims your JWT should contain.

Claims	type	Required	Description
iat	string	x	Time the token was generated. The value must be the number of seconds since UNIX epoch. If this is more then 1 minute Pandium will reject the token.
jti	string	x	A unique id for the token that is used to protect against replay attacks by making sure the token is used only once.
sub	string	x	Unique ID of the primary user in your system. This may be an email, site id, or other identifying value. Pandium uses this to uniquely identify the user. If the user does not exist in Pandium, it will be created.
ti	object		The Tenant Info Object. This object is used to pass information about the end-customer user that you need to tell Pandium about.

The table below provides a list and descriptions of the properties of the object mentioned above.

Property	Type	required	Description
udn	string		The user's display name
ufn	string		The user's full name
uem	string		The user's email
ili	array(string)		An array of installed external integrations, whose ids match the ids of the integration tiles in the Marketplace, that are currently active, and would like to be shown as such in the Marketplace.
aid	string		Auditable user id (if different from sub)
adn	string		Auditable users display name (if different from sub)
xti	object		A place to store extra props that may be need to power your company's marketplace experience

Sample:

{
 "iat": 1621521641,
 "jti": "1cfa7dbf-8110-4237-ad22-410608791b7d",
 "ti": {
   "udn": "Pandium Test",
   "ufn": "Important Person",
   "uem": "[e-mail]",
   "ili": [
     "new-id",
     "something-different"
   ],
   "aid": "",
   "adn": "",
   "xti": {
     "extraProp": "extra value",
     "extraList": [
       "bla",
       "listVal"
     ]
   }
 },
 "sub": "test-pandium-com"
}

Signature:

The JWT signature is produced by concatenating the Base64url encoded header with the Base64url encoded claims, and then signing using the shared secret using HMAC with SHA-256.

HMAC-SHA256(base64url-encoded(header) + "." + base64url-encoded(payload)), <shared secret>)

A complete example.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
    .eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ
    .SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c