Browse Apps
Apps · Deploy and Share

Roles, Sharing, and Access

Share an App environment, give account groups the App and its roles, and check the connections the App calls.

5 min read

Two things decide what a person can do with an App:

  1. Who can open it. Sharing creates the App connection, an MCP server for that environment, and an account administrator gives it to groups.
  2. What they can do in it. App roles, defined in code, decide which functions and table actions a person may use. BotDojo checks them on every call.

Share an environment

Until an environment is shared, only project administrators can open the App, through Preview App.

  1. Open the App, choose the environment, and select Share.
  2. Keep or change the Connection name, then select Set up sharing.

BotDojo creates the App connection and opens its editor. No member can open the App yet, so give a group the App next. From now on, Share opens the connection's editor.

The App connection offers these tools to agents:

ToolWhat it does
show_appShows the App, in the chat or next to it. See its inputs.
One per functionCalls the function, if the person's roles permit it.
One per workflowStarts a run, if the person's roles permit it.
Run toolsFollow, answer, and stop runs. See Start and follow runs.

To keep agents from using a tool, turn it off in the connection's tool settings.

Give a group the App and its roles

An account administrator does this.

  1. Open Account → Groups and open a group whose Scope is Granular Policy Access and Policy Type is Resources, or create one.
  2. Under Apps, switch on the App. Members can now open it with the default role. If no shared apps are listed, share the environment first.
  3. To give other roles, select Roles beside the App and tick them. Unticking the default role replaces it.
  4. Save the group. The App appears under Apps in each member's Workspace.

Roles a newer release no longer defines show as Not in the deployed release so you can untick them. To remove the App from the group, switch it off.

To check what a member sees, sign in as a member of the group. Administrators hold every role, so their view shows no limits. In a local preview, use View as.

How roles are decided

CallerRoles held
Account owner or administrator, or project administratorEvery role.
Member of a group that has the AppThe default role, or exactly the roles the group picks.
Member of several such groupsEvery group's roles, added together.
Someone with access another way, such as project membershipThe default role.
An agent acting for a personThat person's roles.
An agent running without a personIts own groups' roles, or the default role; never every role.

Picked roles that the running release no longer defines give nothing.

Roles come from code

Each role in botdojo.app.ts permits a list of functions and, for each table, the actions read, create, patch, and archive. One role is the default role: keep it to what anyone with access may do. Roles ship with each release, and a deploy shows role changes before you confirm. See Roles.

Review roles in Security

On the App page, the Details tab has a Security section. It lists the roles of the running release, the Connections this app uses, and which groups hold which roles. To change who holds a role, use the group editor.

Connections the App uses

An App's functions can call other systems through connections. The App's code declares each connection by its path and lists the only tools it may call. An account administrator can give groups a plugin so each person connects their own account.

A call runs as the person using the App, from the project they opened it in. It uses that project's connection at the declared path, else the account's shared connection. The person's access to the connection, the connection's tool settings, and the agent's own policy, when an agent opened the App, can each refuse the call.

Security → Connections this app uses shows how each connection resolves from the current project:

StatusWhat to do
ReadyNothing.
Not connected hereAdd a connection at that path, or share one with the account.
No accessGive the caller the connection through a group.
Asks for approvalThe call cannot proceed. Review the connection's access and tool settings.
Missing tool namesUpdate the connection or the App.

People using the App see a notice when a connection it needs is not ready, with Connect when they can connect it themselves.

What an App may do with a person's connections

Each person also decides what the App may do with their own connections, such as their CRM. This is their App install for the environment, and it starts at deny all. When the App needs a connection tool, it asks, and the person chooses for each tool:

ChoiceWhen the App calls the tool
AllowThe call runs, within the person's own access.
Ask each timeBotDojo asks: Approve once (for this session of the App), Approve always (saves Allow), or Deny.
Deny, or not setThe call fails with PERMISSION_REQUIRED.

An Ask each time tool fails with AUTHORIZATION_REQUIRED where nobody can answer, such as an agent's call. People change their choices from the gear icon on the App; an agent cannot. An App set to run as an agent identity uses that agent's access instead. The App's own data and functions never need permission.

For the code, see Ask for the person's permission.

Whose identity runs use

By default an App's workflow runs belong to the person who starts them. To have every run act as one agent instead, open Settings and, under Advanced, set Run as to an agent with its identity turned on. See Where runs live.

See who used the App

The Activity tab lists who called which function, who started or answered which workflow run, and which connection tools were called. Inputs and outputs are never recorded; a failure shows only its error code.

Next steps