Flowlu Marketplace FAQ

Authentication and authorization

What authentication methods are supported for Marketplace apps?

Authentication identifies the current account user, and it works only through an access token obtained via OAuth 2.0.

On whose behalf is an API request executed?

A request runs on behalf of whichever user's access token you pass in the header.

If your app is embedded in the interface and uses the JS SDK to make requests, those requests always run with the access token of the currently authorized user. Your app can also make requests with any user's token from its backend, according to its own logic.

When should I use OAuth 2.0 instead of an API key?

An API key is issued per account. Installing a public app on many accounts would mean issuing a new key for every account, and your app would have to track which key belongs to which account. An API key also isn't tied to a user, so you can't authenticate a specific user with it.

OAuth 2.0 avoids all of this: access tokens aren't tied to an account, but to the user and the app.

Can I make API requests from frontend code, or should sensitive operations go through the backend?

You can call the API from both the backend and the frontend, but from the frontend, only ever use the current user's token. Request data, including the token, is visible in the browser through developer tools, so a user could read another user's token and reuse it freely.

When your app uses the JS SDK, the currently authorized user's token is always used, and frontend requests run on their behalf.

How do manifest permissions correspond to API access?

The manifest declares a list of scopes. Each scope represents a set of models (entities) within a module, plus a level of access to them. There are two access levels: read-only (read) and full access (full). Every scope has a code.

Scopes control:

• the webhooks your app can register,
• the app settings tied to module models (users, CRM accounts, invoices, and so on),
• the API requests your app is authorized to make against module models.

Available scopes:

Scope	What it grants
users	The User model
user.me	The User model, restricted to the currently authorized user
crm	All models in the CRM module
crm.accounts	crm.account, crm.company, crm.contact, crm.phone, crm.email
crm.deals	crm.leads, crm.leadsitems
products	All models in the products module
fin	All models in the fin module
fin.invoices	fin.invoices, fin.items, fin.itemsrelation
st	All models in the st module
task	All models in the task module
agile	All models in the agile module
calendar	All models in the calendar module
timetracker	All models in the timetracker module
knowledgebase	All models in the knowledgebase module
workspace	All models in the workspace module
orgchart	All models in the orgchart module
customlists	All models in the customlists module

Scope precedence Two rules decide what applies when scopes overlap:

• Same scope, different levels. If you declare a scope with both read and full, only the higher level (full) is used.
• General and specific together. If you declare both a module scope and a narrower one from the same module (for example crm and crm.accounts), only the general scope (crm) is used, and the specific one is ignored.

---

Private and public apps

Is moderation required for private apps?

No. Private apps don't require moderation.

Is re-moderation required for every update to a public app?

Changes to the description, support information, banners, and logos don't require re-moderation.

Every new app version does. We review the declared functionality, whether the app works as described, security, and whether the requested scopes are sufficient and justified.

---

App lifecycle

What lifecycle actions are available?

In the Developer Console, you can:

• create an app,
• edit an app,
• deactivate or activate an app,
• publish or hide an app in the Marketplace catalog,
• delete an app,
• create a new version,
• edit a version,
• submit a version for moderation,
• publish or hide a version by changing its status,
• install a version on another account via a link,
• install a version on the current account.

For an app already installed on an account, an administrator can:

• uninstall it,
• set access for user roles and groups,
• change app-level settings,
• change user-level settings.

The installed app is embedded in various parts of the interface and can use the JS SDK.

What data does the app receive during installation, update, or deletion?

The generic miniapp framework doesn't deliver install, update, or delete events to the app itself. Specific integration types, such as telephony or communication channels, define their own lifecycle hooks, covered in their respective guides.

Once the app is running on an account in a user's interface, the app endpoint at the integration point receives:

• the protocol (http/https),
• the account domain (for example, mycompany.flowlu.com),
• the interface language code (en/pt/es),
• the embedding code and its unique id (from the manifest),
• the unique app code (for example, da58bcec-8e2f-11f0-9f3e-eac2b61c1667),
• the version number (for example, 1.0.0).

Using the JS SDK, the app can also:

• obtain the current user's access and refresh tokens,
• obtain app settings,
• obtain user settings,
• make API requests within the scopes and permissions declared in the manifest, for the current user,
• display interface elements (notifications, alerts, modal windows, side panels, navigation, and so on).

What happens to an app's configuration and data when it's deleted?

When an app is uninstalled from an account, Flowlu removes:

• app settings and user settings values,
• files from app settings,
• webhooks the app registered,
• user role and group settings for the app.

The app stops being embedded in the interface.

When an app is deleted from the Developer Console, all of the above happens for every account where it's installed, one account at a time. The app's access and refresh tokens for all users are deleted as well.

What happens on an app update?

Flowlu compares the manifests of the installed version and the new version, then updates the registered webhooks to match the new manifest: webhooks from the old manifest are removed, and webhooks newly specified are registered.

App settings, roles, and files are preserved across an update. The app stops being embedded in any location dropped from the new manifest, and starts being embedded in any location the new manifest adds.