> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Share and use mini apps

> Share mini apps with roles, restrict who can edit them, pin dashboard apps under Reports & Apps, and use inbox widgets beside each session in the inbox.

After an app is published, you decide which roles can open it and who can change it. Dashboard apps can be pinned for the whole workspace, and inbox widgets show up beside sessions for the people they're shared with.

> [!NOTE]
>
> Share from **Apps** in your [OpenCX dashboard](https://platform.open.cx/apps): open the app card's menu and choose **Share**. Changing who can open an app requires **Roles settings** Write and edit access to the app.

## Find apps in the library

**Apps** shows a different library depending on your role:

* **Authors** (**Mini apps** Write) see every app, grouped into **Dashboard apps** and **Inbox widgets**, with search and filters for **Status** (**All**, **Live**, **Drafts**), **Owner** and **Tag**. Each card shows the live version (**v3**), **Draft**, or **No build**. The card menu offers **Open**, and on apps you can edit, **Share**, **Edit details** and **Delete**.
* **Everyone else** sees the published apps they can open. Members with **Mini apps** Read can open every published app.

Opening a dashboard app shows it in Companion. Opening an inbox widget takes you to the inbox on your most recent session, where the widget runs.

**Edit details** changes an app's **Name**, **Icon**, **Description** and **Tags**. Search matches the name and description.

## Share an app with roles

Sharing works by role. An app with no roles selected stays private to admins and members with the **Mini apps** permission.

**1. Open Share**

In **Apps**, open the app card's menu and choose **Share**. In the preview, the **Share** icon appears when the live version is selected.

**2. Pick roles under Can open**

Select the roles whose members can open the app. Changes save immediately.

**3. Limit an inbox widget to channels (optional)**

For an inbox widget, the channel picker at the end of the row limits the channels it shows on. Leave it empty for every channel.

You can also choose roles under **Who can open it** when you publish. The **App link** at the bottom of **Share** is a copyable link to the app. It doesn't grant access: the recipient still needs one of the selected roles.

> [!NOTE]
>
> Dashboard apps open in Companion, so the member's role also needs **Companion** or **Mini apps** Read. Inbox widgets don't need either.

A published app runs with the permissions approved at publish, so the people you share it with see what the app shows, even when their own role can't. See [What an app can read or change](https://docs.open.cx/apps/build-and-publish.md#what-an-app-can-read-or-change).

## Control who can edit

Mini apps and inbox widgets have an owner and a list of people allowed to edit them. Creating an app makes you its owner. By default, everyone with app edit permission (**Mini apps** Write) can edit it.

Editing always requires app edit permission in the workspace. An empty editor list allows everyone with that permission. Selecting people restricts editing to those people and the owner. This restriction applies to admins too. Being able to open an app does not grant app edit permission.

### Invite or remove editors

1. Open **Apps** and choose **Share** from the app's menu.
2. Under **Can edit**, leave the picker empty to allow everyone with app edit permission, or select people to restrict editing. The picker includes you as the owner. Select only yourself to allow only you to edit.
3. Remove someone from a restricted list to revoke their editing access. Clearing the list allows everyone with app edit permission again. Changes save immediately. The owner always retains access, even when selecting only other people.

Only the owner can change this list. Invited editors can change code, app details and widget channels; save versions; publish or unpublish; and delete the app. Changing the roles under **Can open** also requires the **Roles settings** Write permission.

Removing workspace edit permission or organization membership prevents someone from editing even if their name remains on the app's editor list. Unavailable editors remain selected until the owner removes them; changing another selection does not remove them automatically. They can edit again only after their workspace membership and app edit permission are restored.

### Transfer ownership

In **Share**, choose a teammate under **Transfer ownership**, then select **Transfer ownership**. The new owner must have app edit permission.

The new owner controls the editor list. Existing editors keep access, including the previous owner. The new owner can remove the previous owner afterward. Transfer ownership before leaving the organization. If the owner has already left, existing editors can keep editing, but ownership recovery requires support.

### Apps without an owner

Apps created before editor access existed start with an empty editor list, preserving editing for everyone with app edit permission. They are not assigned an owner automatically. Contact support to assign an owner before restricting editors. Published apps remain available to their existing viewers.

### Editing through connected tools

The same restrictions apply when Companion or a connected tool changes an app. The request must identify the acting user, carry the required access, and, when changing an existing app with a restricted list, come from a selected editor or its owner. A bare API key cannot create or change mini apps, even if its scopes allow app writes.

If an edit is refused, ask the owner to add you under **Can edit** and check your workspace app edit permission. Admin permission alone does not override the list.

Companion checks edit access before changing app files or building a new version. If access is denied, it explains that the owner must invite you and leaves the existing app available to open. You can still ask questions about an app you can view.

## Pin apps to Reports & Apps

**Reports & Apps** in the sidebar holds one arrangement for the whole workspace: built-in report pages and published dashboard apps. Each person sees only the entries they can open, so someone with a shared app sees the section even without report access. Inbox widgets never appear here. Arranging requires **Helpdesk settings** Write.

1. In the sidebar under **Reports & Apps**, select **Add**, then pick an app. Report pages are listed above apps.
2. Drag rows to reorder them.
3. To remove an entry, open its menu and choose **Unpin from Reports**.

The same list is under **Reports & Apps sidebar** in [Settings → Workspace](https://platform.open.cx/settings/workspace). A pinned app opens in Companion filling the window. On apps you can edit, the row menu also offers **Edit name & icon** and **Open in Companion**.

## Use inbox widgets

When an inbox widget is published and shared with one of your roles, it appears at the top of **Widgets** in the session sidebar the next time you open a session. It shows only on the channels selected for it.

Your widget pins are your own:

* **Unpin** a widget from its **More** menu, and bring it back with **Add a widget**.
* Drag widgets to reorder them.
* **Full screen** opens a larger view and **Reload** restarts the widget.
* **Edit** in the **More** menu opens the app in Companion, if you can edit it.

A widget grows to fit its content, up to about three quarters of the screen height, then scrolls.

### What a widget knows about the session

A widget receives the open session, the session's contact when there is one, and you as the viewer, with your name and email. Opening another session reloads it with that session. Anything else it shows, such as messages or order details, comes through the permissions approved at publish or the actions it runs.

### Place a widget for everyone with Adjust widgets

With **Helpdesk settings** Write, on a desktop-size window, you can fix a widget's spot in the session sidebar for the whole workspace.

1. Open a session and choose **Adjust widgets** from the session menu, or from a widget's **More** menu.
2. Place the widget among the built-in cards, then select **Save**.

A placed widget shows in that spot for everyone it's shared with, on the channels it's enabled for. Agents can't unpin it; only the layout removes it.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| "You don't have access to" the app | The app isn't shared with any of your roles | Ask someone with **Roles settings** Write and edit access to add your role under **Can open** |
| An access denied page when opening a shared dashboard app | Your role has neither **Companion** nor **Mini apps** Read | Add **Companion** Read to the role in **Settings → Roles** |
| The app "isn't published yet" | It has no live version | Ask an editor to publish a version |
| A widget is missing from the session sidebar | It isn't shared with your role, isn't enabled for this session's channel, or you unpinned it | Check **Can open** and the channel picker in **Share**, or re-add it from **Add a widget** |

***

## Related Documentation

> [card] [Build and publish](https://docs.open.cx/apps/build-and-publish.md)
>
> Versions, permissions and domains.

> [card] [Mini apps introduction](https://docs.open.cx/build-agents/mini-apps.md)
>
> What apps are and who can build them.

> [card] [Workspace settings](https://docs.open.cx/ticketing/workspace-settings.md)
>
> The Reports & Apps sidebar setting.

> [card] [Roles](https://docs.open.cx/security/roles.md)
>
> Create roles to share apps with.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.