Authentication

Overview

Plugin authentication protects your endpoint from unauthorized calls. Every production plugin should verify that a request came from KasiLabs before performing any business action.

Authentication has two separate concerns:

Most plugins need platform verification. Only some plugins need delegated account access.

Platform verification

Each tool call includes a signed platform token in the request headers.

Your endpoint should:

1. Read the token.
2. Verify the signature using the plugin secret.
3. Confirm the token has not expired.
4. Confirm the token is for the expected plugin and tool.
5. Reject the request if verification fails.

The plugin secret is created during sandbox installation or live plugin setup. Save it securely. It is shown once.

What the token proves

A valid token proves:

• The call came through KasiLabs.
• The call is for your plugin.
• The call is for a specific tool.
• The call belongs to a specific organization and WhatsApp number instance.
• The token is recent.

It does not prove that every requested business action should be allowed. Your endpoint should still validate business rules.

Example: a delivery plugin should verify that an order is paid before creating delivery. A ticketing plugin should verify required fields before creating a ticket. A booking plugin should verify availability before confirming a slot.

Customer identity

Plugin calls include a privacy-preserving customer identifier.

{
  "user": {
    "id": "customer_hash",
    "hashVersion": 1
  }
}

Use this ID to keep plugin-side customer records without receiving the raw WhatsApp phone identifier by default.

If your business flow genuinely needs contact information, collect it in the conversation or through your own authorized account flow, then handle it according to your privacy obligations.

Delegated account access

Use delegated access when the plugin needs permission to access an external user or workspace account.

Examples:

• A CRM plugin needs to create leads in the merchant's CRM workspace.
• A calendar plugin needs to book appointments.
• A support plugin needs to create tickets in the merchant's support desk.
• An accounting plugin needs to create invoices.

Delegated access flow

1. The plugin manifest declares delegated access settings.
2. An authorized admin configures the plugin.
3. The user or organization is sent to authorize access.
4. The external service returns authorization to KasiLabs.
5. KasiLabs stores the authorization securely.
6. Future tool calls include an access token for your plugin to use.

Your endpoint does not need to ask the user to authorize manually during every call. If authorization is missing or expired, the platform prompts for reconnection.

Receiving authorization

When delegated access exists, the tool call includes an access token in the request metadata. Use it only for the action requested by that tool call.

Do not log access tokens. Do not send them back in responses. Do not expose them to customers.

Secret handling

Follow these rules:

• Store plugin secrets in a secure server environment.
• Never commit secrets to source control.
• Never expose secrets in browser code.
• Rotate secrets if they are lost or exposed.
• Use separate sandbox and live secrets.

Error responses

Return safe errors. The agent may summarize errors to the customer or operator.

Good:

{
  "error": "authentication_failed",
  "message": "The plugin request could not be verified."
}

Bad:

{
  "error": "signature mismatch using secret sk_live_..."
}

Authorization versus permissions

Do not confuse these:

All of them matter.

Best practices

Verify every request

Even read-only tools should verify platform calls. Read-only data can still be sensitive.

Keep tokens short-lived

Treat platform tokens as short-lived request proof. Do not store them as long-term credentials.

Validate business state

For side effects, require stable references such as order number, ticket ID, booking ID, or approved request ID.

Return customer-safe summaries

The agent uses your response to continue the conversation. Return useful output, not internal logs.

Next steps

• Manifest Reference - Define auth and tool contracts
• Plugin Permissions - Understand plugin and bridge grants
• Platform Bridges - Sign bridge requests safely
• Testing & Debugging - Debug failed requests
• Permissions & RBAC - Understand install and grant boundaries