Roles, Sharing, and Access
Share an App environment, give account groups the App and its roles, and check the connections the App calls.
Two things decide what a person can do with an App:
- Who can open it. Sharing creates the App connection, an MCP server for that environment, and an account administrator gives it to groups.
- 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.
- Open the App, choose the environment, and select Share.
- 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:
| Tool | What it does |
|---|---|
show_app | Shows the App, in the chat or next to it. See its inputs. |
| One per function | Calls the function, if the person's roles permit it. |
| One per workflow | Starts a run, if the person's roles permit it. |
| Run tools | Follow, 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.
- Open Account → Groups and open a group whose Scope is Granular Policy Access and Policy Type is Resources, or create one.
- 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.
- To give other roles, select Roles beside the App and tick them. Unticking the default role replaces it.
- 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
| Caller | Roles held |
|---|---|
| Account owner or administrator, or project administrator | Every role. |
| Member of a group that has the App | The default role, or exactly the roles the group picks. |
| Member of several such groups | Every group's roles, added together. |
| Someone with access another way, such as project membership | The default role. |
| An agent acting for a person | That person's roles. |
| An agent running without a person | Its 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:
| Status | What to do |
|---|---|
| Ready | Nothing. |
| Not connected here | Add a connection at that path, or share one with the account. |
| No access | Give the caller the connection through a group. |
| Asks for approval | The call cannot proceed. Review the connection's access and tool settings. |
| Missing tool names | Update 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:
| Choice | When the App calls the tool |
|---|---|
| Allow | The call runs, within the person's own access. |
| Ask each time | BotDojo asks: Approve once (for this session of the App), Approve always (saves Allow), or Deny. |
| Deny, or not set | The 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.