Permissions & RBAC

Overview

Permissions decide who can see information, change settings, handle customers, move money, and use toolkits. RBAC means role-based access control: you give a person a role for their normal job, then add more specific permissions only where that job needs them.

This matters because your WhatsApp agent can take real actions. It can create orders, request payments, send receipts, escalate chats, schedule reminders, and call installed plugins. Permissions make sure those actions happen inside clear business rules instead of depending on a conversation alone.

Use this page when you need to answer:

• Who can install or configure a toolkit?
• Which WhatsApp instance can use a toolkit?
• Which employee can fulfill orders?
• Which employee can issue refunds or request payouts?
• Which employee can edit the catalog or receipt branding?
• Which plugin can the agent call?
• Which tools should stay unavailable even if the agent asks for them?

The access model

KasiLabs separates access into layers. Each layer answers a different question.

These layers are intentionally separate. Installing a toolkit does not automatically give every employee access to its dashboard. Granting a toolkit to one instance does not grant it to every other instance. Allowing the agent to use a toolkit does not mean an employee can manage refunds, payouts, or settings.

How permissions are enforced

Permissions are checked at the point where the action happens.

The agent does not get unlimited power just because it is intelligent. It only receives tools that are available for the active instance. If a toolkit or plugin is not granted to that instance, the agent cannot call those tools in that conversation.

For sensitive actions, the system should prefer explicit dashboard actions by authorized employees. The agent can help collect information, explain policy, create normal checkout flows, or prepare a request, but actions such as refunds, payout requests, cancellation approval, and settings changes should be limited to employees with the correct permission.

Roles versus toolkit permissions

A role is broad. A toolkit permission is specific.

Example:

This prevents accidental overreach. A support agent may need to answer "Where is my order?" but does not need to edit payout accounts. A driver may need to mark an order delivered but should not issue refunds.

Toolkit permissions

Toolkits are business capabilities. They can expose dashboard pages, AI tools, background workflows, and cross-toolkit actions.

Payments permissions

E-Commerce permissions

Scheduling, image, browser, and sandbox permissions

Other toolkits follow the same model: install the toolkit, grant it to an instance, then give users only the dashboard or action permissions they need.

For example, scheduling access should be limited because scheduled messages can reach many customers later. Image generation access should be limited if it affects brand content or paid usage. Browser and file automation access should be limited when it can interact with external accounts.

How plugins fit into permissions

Plugins are external capabilities added to the agent. A plugin can expose one or more tools, such as lookup_customer, create_ticket, check_inventory, or book_delivery.

Plugin permissions have three practical gates:

1. Installation gate - An authorized user installs the plugin for the organization.
2. Instance grant gate - An authorized user grants the plugin to a specific WhatsApp instance.
3. Tool execution gate - The agent only receives the plugin tools for the active instance if the plugin is installed, active, and granted.

This means a sales instance can have a CRM plugin while a legal-consulting instance does not. A support instance can use a ticketing plugin while a marketing instance cannot.

Plugins should not bypass toolkit permissions. If a plugin performs a sensitive business action, design it so the action still respects the business permission boundary. For example:

• A CRM plugin can read a customer profile for support.
• A delivery plugin can create a delivery job after an order is paid.
• A finance plugin should not issue refunds unless the employee or workflow has refund authority.
• A fulfillment plugin should not mark an order delivered unless that action is part of an authorized fulfillment workflow.

Plugin permission requests

Plugin authors declare requested plugin permissions in the plugin manifest. These permissions describe what the plugin itself can do in its connected external system.

Example:

{
  "permissions": [
    {
      "key": "delivery:jobs:create",
      "label": "Create delivery jobs",
      "description": "Allows the agent to create delivery jobs after payment is confirmed."
    }
  ]
}

These declarations help admins review risk before installing or granting the plugin. They do not replace platform toolkit permissions.

If a delivery plugin needs to create delivery jobs only after payment, the instance still needs Payments or E-Commerce granted so the agent can verify payment or order state. If a booking plugin needs reminders, the instance still needs Scheduling granted so the agent can create reminders through the Scheduling toolkit.

Platform bridge permissions

Some plugin workflows use a dedicated platform bridge instead of an agent tool call. A bridge is a narrow endpoint for one specific platform-owned action.

Bridge permissions are granted on the plugin's instance grant:

<recipient_scope> is current_chat, known_contact, or external_recipient. If a plugin is missing a required bridge permission, the request is rejected before the platform changes state. A payment bridge without plugin:payments:initiate:current_chat cannot create payment requests for the active customer.

Obligation plugins can also work in polled mode. The plugin manifest marks a tool with metadata.capability: "obligations.list_due". KasiLabs periodically calls that tool, but it still checks scoped message and escalation permissions before sending anything.

Toolkit-to-toolkit permissions

Some workflows require more than one toolkit.

The safest rule is:

One toolkit may provide context to another, but sensitive actions still require the permission of the toolkit that owns the action.

Examples:

• E-Commerce can show payment status, but Payments owns refunds and payout records.
• Payments can confirm an order is paid, but E-Commerce owns fulfillment status.
• Escalations can assign a human, but the human still needs the right commerce or payment permission to change order or money state.
• A plugin can provide external data, but it should not be treated as permission to override platform policy.

Instance assignments

Assignments decide which employee is responsible for which work.

Use assignments when:

• You have multiple WhatsApp instances.
• You separate sales, support, fulfillment, and services.
• You need paid service sessions handled by a specific consultant.
• You want escalation queues to route to trained employees.

Examples:

Assignments are operational responsibility. Permissions are authority. A person can be assigned to a queue but still lack authority to perform a sensitive action.

Scenario: Matuzo home goods and services

Matuzo sells kitchenware, small appliances, repairs, and paid home-service consultations through WhatsApp.

They run three WhatsApp instances:

They have six teams:

Step 1: Create roles

Matuzo creates roles that match real jobs.

Step 2: Install toolkits

The owner installs:

• E-Commerce for catalog, carts, orders, inventory, fulfillment, services, and receipts.
• Payments for checkout, payment verification, receipts, refunds, payouts, disputes, and settlements.
• Scheduling for delivery reminders and follow-ups.
• Optional plugins for delivery, accounting, or CRM workflows.

Installation makes a capability available to the organization. It does not automatically give the agent or employees access everywhere.

Step 3: Grant toolkits to instances

Matuzo grants:

Now the sales agent can create carts and request payment. The support agent can look up order and payment context. The services bot can sell timed consulting sessions.

Step 4: Configure Payments

The finance manager opens Payments -> Settings.

They complete:

• Business name and description.
• Contact email and phone.
• Settlement bank and account number.
• Receipt logo and thank-you text.
• Default collection flow.

When they save, the system checks the settlement account details with the payment network. If the bank and account number resolve to a valid account name, the payment account becomes connected. If the account cannot be verified, the settings are saved as a draft so Matuzo can continue testing non-live flows without enabling live settlement.

Step 5: Configure E-Commerce

The catalog team opens E-Commerce -> Settings and configures:

• Store name: Matuzo Home & Kitchen.
• Currency: KES.
• Delivery and pickup rules.
• Default delivery fee.
• Stock reservation window.
• Commerce receipt logo and footer.

Then they open E-Commerce -> Catalog and add:

Services do not need images. They use a clear description, price, and duration.

Step 6: Assign employees

Matuzo assigns:

• Sales agents to the Sales instance.
• Support agents to the Support instance.
• Fulfillment staff to the Sales order queue.
• Service specialists to paid service sessions.
• Finance managers to refund, settlement, payout, and dispute review.

Step 7: Customer order flow

A customer messages Matuzo Sales:

Do you have a Japanese knife for home cooking?

The agent can:

1. Search the active catalog.
2. Recommend matching products.
3. Add the selected knife to a cart.
4. Collect customer name, phone, and delivery address.
5. Show the order total.
6. Create the order after confirmation.
7. Request payment through Payments.
8. Wait for payment confirmation.
9. Send a WhatsApp text summary and PDF receipt.
10. Move the paid order into the fulfillment queue.

The fulfillment team can then mark the order as preparing, out for delivery, and delivered. They cannot refund it unless they also have refund permission.

Step 8: Refund flow

A customer later says:

The knife arrived damaged. I want a refund.

The support agent can:

1. Open the chat.
2. View the order and payment context.
3. Ask for a photo or explanation.
4. Create an internal refund request or escalate to finance.

The finance manager can:

1. Review the order.
2. Confirm policy and refund amount.
3. Issue the refund.
4. Update the customer through WhatsApp.

The AI can assist the conversation, but it should not independently issue the refund unless the business has deliberately designed an approved automated policy for that case.

Recommended permission sets

Small shop

Service business

Larger operation

Common mistakes

Giving support agents refund access

Support agents usually need to collect details and escalate. Finance or managers should issue refunds.

Installing a toolkit and assuming the agent can use it

Install the toolkit, then grant it to the correct instance. The agent only receives tools that are granted to that instance.

Granting a plugin too broadly

Grant plugins only to the instances that need them. A plugin for delivery operations should not be available to an unrelated legal consulting instance.

Mixing payment settings with commerce settings

Use Payments settings for collection, settlement, payout, and standalone receipt branding. Use E-Commerce settings for store profile, product/service receipts, delivery rules, and order behavior.

Letting the AI become the approval authority

The AI can follow policy, collect data, and prepare actions. Sensitive approvals should belong to employees or explicitly configured business workflows.

Next steps

• Integrations - Install and grant toolkits
• Payments - Configure collections, settlement, payouts, and receipts
• E-Commerce - Configure catalog, orders, fulfillment, and paid services
• Developer Overview - Build plugins that respect permission boundaries