Plugin Permissions

Why plugin permissions exist

Plugins let an external system participate in conversations on a connected WhatsApp number instance. A gas-ordering plugin might create delivery orders. A legal-services plugin might request payment before a consultation. A reminder plugin might schedule follow-ups.

That authority must be explicit because it can affect money, customer messages, orders, refunds, escalations, and operations. Plugin permissions answer four questions:

• Which plugin is installed for the organization?
• Which connected WhatsApp number instance may use it?
• Which plugin tools may the AI agent call?
• Which platform-owned actions may the plugin request directly through a bridge?

The aim is deterministic enforcement. If a plugin is not allowed to request a refund, the platform refuses the refund before money moves. The decision does not depend on prompt wording.

The four gates

Every plugin action passes through separate gates.

Installing a plugin does not grant it to every WhatsApp bot. For example, a business can install a CRM plugin for the organization, grant it to the support WhatsApp number instance, and leave it disabled on the sales WhatsApp number instance.

Granting a plugin to a WhatsApp number instance also does not approve every sensitive action. A merchant can allow a plugin to create orders while refusing refunds.

Two permission families

Declare requested permissions in the plugin manifest:

{
  "permissions": [
    {
      "key": "gas:orders:create",
      "label": "Create gas orders",
      "description": "Allows the plugin to create gas delivery orders in the merchant's gas system.",
      "default": true
    },
    {
      "key": "plugin:payments:initiate:current_chat",
      "label": "Request payment from the current WhatsApp customer",
      "description": "Allows the plugin to ask KasiLabs to create a payment request for the customer currently chatting with this WhatsApp number instance."
    }
  ]
}

Use two kinds of permission keys:

Plugin-owned permissions are still useful. They tell the merchant what your plugin claims it can do, and your plugin backend should enforce them for your own business domain.

Platform bridge permissions are reserved by KasiLabs. They are enforced before a bridge action runs. If Gas OS lacks plugin:payments:initiate:current_chat, the payment bridge rejects the request before creating a payment.

Recipient scopes

Most dangerous actions are scoped by recipient.

Use current_chat whenever possible. The plugin receives a short-lived context.currentChat.token when the AI calls one of its tools during a customer conversation. The plugin sends that token to a bridge instead of sending the raw WhatsApp JID.

Example bridge recipient:

{
  "recipient": {
    "type": "current_chat",
    "token": "<context.currentChat.token>"
  }
}

For known_contact and external_recipient, the plugin must provide a JID. External-recipient permissions should be granted rarely because they let a plugin initiate actions toward people outside the active conversation.

Platform permissions available today

Payments:

E-Commerce:

Messaging and escalation:

If one is missing, the bridge fails with a direct error such as:

Plugin is missing permission: plugin:payments:initiate:current_chat

Permission combinations

Sensitive workflows usually need more than one permission.

The bridge checks permissions at execution time. A manifest declaration alone is not enough; the merchant must grant the permission on the WhatsApp number instance.

Dependency-only platform capabilities

Payments, M-Pesa, and E-Commerce can be available to a plugin without being exposed as raw agent tools. This is the preferred setup when a plugin owns the business workflow.

Example for a gas ordering plugin:

• Gas OS tools are agent-facing: list_products, quote_order, create_b2c_order.
• E-Commerce is dependency-only: it stores synced catalog items and durable orders.
• Payments or M-Pesa is dependency-only: it requests payment through the active provider.

The agent talks to the Gas OS tools. Gas OS talks to KasiLabs through signed bridges. The platform remains agnostic; it only enforces generic permissions and state transitions.

When a plugin has E-Commerce bridge permissions on a WhatsApp number instance, raw platform commerce_* tools are hidden from that agent. This reduces the risk of the AI bypassing the plugin's domain flow and calling a generic order tool directly.

Receipts are generated by the shared platform receipt action after payment succeeds. The customer receives one WhatsApp document message: the receipt PDF plus a short text summary as the caption.

Tool calls versus bridge calls

There are two ways a plugin participates.

Use normal plugin tools when the agent needs reasoning. Use bridges when the plugin needs a deterministic platform-owned action.

Deterministic enforcement

The bridge does not ask the AI whether an action is allowed. It checks:

1. The request signature is valid.
2. The plugin is installed.
3. The plugin is granted to the target WhatsApp number instance.
4. The required permission is granted.
5. The recipient scope is allowed.
6. The current-chat token matches the plugin, organization, WhatsApp number instance, and expiry time.
7. The request has an idempotency key for side effects.
8. The request is recorded with status and result/error snapshot.

That means a retried request can return the same result instead of creating duplicate orders, duplicate payments, or duplicate reminders.

Relationship to employee permissions

Plugin permissions control what the plugin may request. Employee permissions control what dashboard users may do.

Example:

• Gas OS may request plugin:ecommerce:orders:create:current_chat.
• A fulfillment employee may have permission to mark the order out for delivery.
• A finance employee may have permission to issue refunds.

The plugin grant does not make every employee a finance manager. Employee permissions are still enforced in the dashboard and operational workflows.

Related pages

• Platform Bridges - Bridge endpoints, payloads, and examples
• Manifest Reference - How to declare permissions
• Testing & Debugging - How to test missing-permission cases