Operating a Plugin

Plugin Lifecycle

The lifecycle of a plugin begins when your plugin is installed and ends when your plugin is uninstalled.

Every plugin must handle the plugin_install and plugin_uninstall events.

Installing a plugin

💡

The plugin is successfully installed if actions 1-2 are successful, and regardless of the result of actions 3-4.

Every time your plugin is installed:

1. A Torii API key you can use to interact with the Torii API on behalf of the installing organization is generated and passed to you.

   🚧

   We encourage you to keep the API Key and any other sensitive data secure and encrypted.

2. If there are app fields defined in your plugin’s manifest:

   1. A custom application fields group named after your plugin is created
   2. All the fields defined in your manifest are created under this group

3. A POST request is sent to your callbackUrl with the plugin_install event (see more details below).

4. A “Plugin was installed” email is sent to all of the Torii admins in the organization

/POST callbackUrl
{
  configuration: {
    torii: {
	    apiKey: string // Use this API key to interact with Torii's API,
			idOrg: number // the ID in Torii of the organization that installed your plugin,
			version: string // the version the plugin was installed with
			installedBy: {
	      firstName: string,
        lastName: string,
        email: string
      } // an object containing information about the user who installed your plugin
    },
		vendor: {
			// the data you requested the user to insert while installing your plugin, 
					using the `config.consent.fields` property in the `manifest.json` file
			[field1.name]: field1.value,
			[field2.name]: field2.value,
			...
		}
  },
	event: "plugin_install"

Uninstalling a plugin

💡

The plugin is successfully uninstalled if actions 1-2 are successful, and regardless of the result of actions 3-4.

Every time your plugin is uninstalled:

1. The Torii API key created upon installing your plugin is revoked.
2. Any custom fields and groups created when your plugin was installed are removed.
3. A POST request is sent to your callbackUrl with the plugin_uninstall event (see more details below).
4. A “Plugin was uninstalled” email is sent to all of the Torii admins in the organization

/POST callbackUrl
{
  configuration: {
    torii: {
			idOrg: number // the ID in Torii of the organization that uninstalled your plugin
    }
  },
	event: "plugin_uninstall"
}

🚧

Make sure to return a response - success or failure - as fast as possible, as the user is waiting for an indication whether the install/uninstall process was successful.

Verifying requests from Torii

Torii signs its requests using a secret unique to your plugin.

With the help of signed secrets, your plugin can more confidently verify whether requests from Torii are authentic.

Understanding signed secrets

Torii creates a unique secret for your plugin and shares it with you. The secret is generated when you create your plugin and it is returned in the API’s response.

Verify requests from Torii with confidence by verifying signatures using your signing secret.

On each HTTP request that Torii sends, Torii adds a x-torii-signature HTTP header. The signature is created by combining the signing secret with the body of the request sent using a standard HMAC-SHA256 keyed hash.

The resulting signature is unique to each request and doesn't directly contain any secret information. That keeps your plugin secure, preventing bad actors from causing mischief.

// Example Node.js code demonstrating how to validate the request
const hash = crypto.createHmac('SHA256', process.env.SECRET).update(payload).digest('base64')
if (hash !== headers['x-torii-signature']) {
	throw new Error("Invalid request!")
}

Publishing a new version

You can upload as many versions as you’d like as long as they pass our validation requirements. However, plugins are always installed with the latest version existing at that time.

Auto-upgrade mechanism

To provide a smooth consumer and developer experience, we have implemented an auto-upgrade mechanism. Every time a new version is uploaded and app fields that existed in the previous version were removed or new app fields were added - Torii will automatically perform the necessary changes for every organization with an active installation.

Currently, we do not support modifying fields. If you want to modify an existing field, you have to remove it and create a new one instead.

🚧

Changes to other information, such as the consent data, will not impact existing consumers, but it might require you to maintain multiple versions.

How does Torii know what fields were removed and/or created?

Torii compares the previous version’s manifest against the latest version’s manifest to find changes.

Changes in app fields are determined by the key property of the field.

Deleting a plugin

💡

Use the Delete plugin API to delete a plugin

You can delete a plugin anytime, whether it has active installations or not.

Once you delete a plugin, it is removed from the marketplace, and any data associated with your plugin is removed from any organization that installed it, e.g. custom app fields created by the plugin, widgets, etc.

Updating Application Fields

💡

Use the Update app API to update the fields of an application.

Updating custom application fields is done using the field’s generated internal name. To make it easier for you, and since internal names are dynamically generated and can differ between organizations, plugin developers can use the key defined within the manifest file to update the corresponding field.

For example, if your manifest file looks like the one in our Hello World example, you can make the following API request to update the username field:

curl --location --request PUT 'https://api.toriihq.com/v1.0/apps/{idApp}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
    "username": "John Doe"
}'

Generating an API Key (for private plugins)

An API key is generated when a plugin is installed and it allows you to interact with Torii’s API on behalf of your organization.

The API key is included inside the payload sent in the HTTP request to your callbackUrl.

If your manifest file does not include a callbackUrl property, you can use the Generate an API key API instead.

Please note:

1. The plugin must be private.
2. The plugin must be installed on your organization.
3. Calling this API will revoke all previously generated API keys (associated with this plugin) and generate a new key.