Roles & permissions
A role answers one question: which tools may this caller invoke? It applies to people and to agents identically, because both reach the gateway through a credential and every credential carries exactly one role.
The four built-in roles
| Role | Intended for | Typical scope |
|---|---|---|
| Admin | IT or engineering | Every connector, every setting, every seat. The only role that can create roles, invite people and manage billing. |
| Finance (CFO) | Finance team | Read and write on financial systems, scoped to the numbers rather than the whole business. |
| Manager | Department heads | Read and write on the connectors their department needs, and nothing beyond it. |
| Viewer | Analysts, auditors, observers | Read only. Sees what happened without being able to change anything. |
What each role sees in the console
Roles govern the dashboard as well as the gateway, so someone who cannot invoke billing tools also does not land on a billing screen. Admin always sees everything.
| Section | Admin | Finance | Manager | Viewer |
|---|---|---|---|---|
| Home | ✓ | ✓ | ✓ | ✓ |
| Connectors | ✓ | ✓ | ✓ | ✓ |
| Usage | ✓ | ✓ | ✓ | ✓ |
| Data Retention | ✓ | ✓ | ✓ | — |
| Billing | ✓ | ✓ | — | — |
| Team | ✓ | — | — | — |
| Roles & Access | ✓ | — | — | — |
| Settings | ✓ | — | — | — |
| Gateway Monitor | ✓ | — | — | — |
Admins can adjust which sections the other three roles see, under Roles & Access. Admin's own visibility is fixed, because a platform where the administrator can lock themselves out of administration is a support call waiting to happen.
Custom roles
The built-in four cover common shapes. When you need something specific, a sales rep who may use Salesforce but must never touch M-Pesa, for instance, create a custom role.
- Roles & Access → New role. Give it a name that describes the job and a description that will still make sense to someone else in six months.
- Pick tools from the live catalogue. The tool list is fetched from the gateway when you open the form, so you are choosing from what actually exists in your tenant right now.
- Save, then bind it. A role does nothing until something carries it. Assign it to a seat under Team, or to an API key when you generate one under Settings → API Keys.
Full Access is available even when the catalogue is not. If the gateway is briefly unreachable the role form will say so and the tool picker will be empty. You can still create a Full Access role in that state; you cannot pick individual tools until the catalogue loads. Wait rather than granting Full Access as a workaround.
How allowlists are evaluated
A role holds a list of permitted tool names, or the wildcard * meaning full access.
Evaluation is deliberately boring, because a permission system with interesting behaviour is a
permission system nobody can reason about.
- Deny by default. A tool that is not on the list is refused. There is no inherited or implicit grant.
- Checked on the tool name. Not on the wording of the request. Rephrasing the prompt does not change the outcome.
- Applied before discovery. The assistant never sees tools it may not call, so it does not try and then fail.
- Enforced at the gateway. Not in the client, where a determined caller could ignore it.
- One role per credential. No union of roles, no precedence rules to unpick.
Designing a role that lasts
- Write the job down first. One sentence: "reconciles collections against invoices and flags non-compliant suppliers". The tool list falls out of the sentence.
- Grant reads freely, writes never by accident. Every write tool should be a decision someone made on purpose, not something that came along for the ride.
- Start too tight. Denials show up in the audit log with the tool name attached, which makes widening a role a two-minute job driven by evidence.
- Review when the job changes. Roles outlive the projects that created them. A quarterly pass over the role list catches the ones nothing carries any more.
Changing a role that is in use
Edits take effect on the next request. Nothing needs reissuing: credentials point at the role, so tightening an allowlist immediately narrows every key and every seat that carries it. Widen the same way. If you need to stop one specific integration without affecting the others, revoke its key rather than editing the shared role.