Scopes

Every Personal Access Token (PAT) carries a set of scopes — the list of actions that token can perform against the public API. You pick scopes at creation time, and they’re immutable afterward — to change them, mint a new token and revoke the old one.

How they’re validated

On every request, the auth guard loads the token and puts its scopes on the request context. Each endpoint declares the scope it needs with @RequireScopes('messages:send'). If the scope is missing, the response is 403 Forbidden with code: INSUFFICIENT_SCOPE.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Forbidden",
    "details": {
      "required": ["messages:bulk"],
      "missing": ["messages:bulk"]
    }
  }
}

Unlike auth errors (which are intentionally generic), authorization errors spell out which scope is missing — because you already authenticated successfully; you just lack permission.

Catalog

The catalog lives in the api_scopes MongoDB collection. The portal pulls it via GET /api/v1/api-scopes and builds the create-token modal dynamically, so adding a new scope doesn’t require a frontend deploy.

Scope	Group	Action
`messages:send`	messages	Send a single message of any type, on any connected channel.
`messages:bulk`	messages	Bulk-send a template to many recipients and read campaign status.
`templates:read`	templates	Read the company’s approved template catalog.
`templates:create`	templates	Create WhatsApp templates and submit them to Meta.
`templates:update`	templates	Edit an existing template (components, category, language, status).
`flows:read`	flows	List and read WhatsApp Flows.
`flows:write`	flows	Create, update, publish and delete WhatsApp Flows.
`contacts:read`	contacts	List and read the messaging contacts of your company.
`contacts:write`	contacts	Create and update contacts, including custom fields.
`contacts:delete`	contacts	Delete contacts and their change history. Permanent.
`channels:read`	channels	List channels (`/v1/channels`) and WhatsApp numbers (`/v1/whatsapp/numbers`).
`channels:connect`	channels	Start and poll WhatsApp Business connect sessions from the CLI or your backend.
`webhooks:read`	webhooks	List outbound webhook subscriptions and read delivery history.
`webhooks:manage`	webhooks	Create, update, rotate secret, delete subscriptions, and fire test events.
`knowledge:read`	knowledge	Read the knowledge base tree.
`knowledge:write`	knowledge	Create folders and documents (markdown → BlockNote).
`knowledge:delete`	knowledge	Delete nodes (folders and documents) from the knowledge base.
`knowledge:query`	knowledge	Query the knowledge base with full-text, vector, or hybrid search.
`knowledge:assign`	knowledge	Assign nodes of the knowledge base to an assistant’s workers.
`assistants:read`	assistants	List assistants, read the blocks that make up their prompt, read block content and version history, and list webhook functions.
`assistants:write`	assistants	Create and configure assistants, create and edit prompt blocks, and manage the webhook functions they can call.
`scheduling:branches:read`	scheduling	List branches and get details.
`scheduling:services:read`	scheduling	List services and details (duration, restrictions, allowed professionals).
`scheduling:professionals:read`	scheduling	List professionals and details by branch or service.
`scheduling:availability:read`	scheduling	Query availability by date, by range, and next available slots.
`scheduling:appointments:read`	scheduling	Get an appointment by id within the tenant.
`scheduling:appointments:create`	scheduling	Create appointments with embedded customer data.
`scheduling:appointments:confirm`	scheduling	Confirm appointments (`pending` → `confirmed`).
`scheduling:appointments:cancel`	scheduling	Cancel appointments with an optional reason.
`crm:customers:read`	crm	List and read CRM customers.
`crm:customers:write`	crm	Create and update customers, including custom fields and tags.
`crm:customers:delete`	crm	Delete customers. Permanent.
`crm:tickets:read`	crm	List with filters and read CRM tickets.
`crm:tickets:write`	crm	Create, update, and move between pipeline stages.
`crm:tickets:delete`	crm	Delete tickets. Permanent.
`crm:tasks:read`	crm	List and read CRM tasks.
`crm:tasks:write`	crm	Create and update tasks (status, priority, assignee, due date).
`crm:tasks:delete`	crm	Delete tasks. Permanent.
`crm:notes:read`	crm	List and read CRM notes.
`crm:notes:write`	crm	Create and update notes. The author is the token’s owner.
`crm:notes:delete`	crm	Delete notes. Permanent.
`ecommerce:products:read`	ecommerce	List and read the product catalog.
`ecommerce:carts:read`	ecommerce	List and read carts, including abandoned ones.
`ecommerce:sales:read`	ecommerce	List and read sales, with amounts and payment state.
`loyalty:read`	loyalty	Read programs, templates, memberships, balances and ledger movements.
`loyalty:write`	loyalty	Enroll customers, move points and stamps, issue wallet passes and notify the customer’s card.
`projects:read`	projects	List the projects of your company the token can reach.

The checkboxes in the Create API Key modal load live from the backend. A missing scope means it’s flagged is_active: false in the database.

The MCP server uses the same scopes

The MCP server does not have a scope system of its own. Each of its 101 tools requires exactly the scope its REST counterpart does — keebai_crm_ticket_create needs crm:tickets:write, keebai_contacts_list needs contacts:read, and so on. The tool catalogue lists the mapping. One difference matters when you hand a token to an agent: a missing scope is not a 403. Every tool stays visible in tools/list regardless of your scopes, and the call comes back as a tool error carrying INSUFFICIENT_SCOPE. An agent will happily try something it cannot do and discover the limit afterwards, so pick the scope set deliberately rather than relying on the agent not to reach for a tool.

Scopes are independent from role permissions

Scopes are independent from the role permissions of the user who creates the token. The backend validates what scopes you’re allowed to assign at creation time (each scope must exist and be active in api_scopes), but once minted, the token uses its assigned scopes regardless of later changes to your role. That means:

To create a token you need developer.manage_tokens on your role. Without it you don’t even see the API Keys screen.
Once created, a token’s scopes are fixed. If your role is later trimmed, the token keeps working with its original scopes. To revoke access, revoke the key explicitly.
To use new scopes, mint a new token. You can’t add scopes to an existing key.

Because scopes survive role changes, audit the API Keys table periodically and revoke tokens belonging to people who shouldn’t have access anymore. The Last used column helps find forgotten keys.

Least privilege by example

Pick the smallest scope set that does the job. Splitting messages:send and messages:bulk exists exactly for this — bulk is higher-risk (Meta cost, sender reputation, abuse potential), so isolate it in a key the marketing tool owns, not the transactional backend.

Transactional backend (1:1 notifications)

Only needs to send single messages.messages:send.

Marketing tool / outbound CRM

Needs to launch campaigns and check status.messages:bulk, templates:read.

Template viewer

Read-only browser of the approved catalog.templates:read.

Template provisioning

Creates and maintains the company’s templates without using the portal.templates:read, templates:create, templates:update.

Full-stack integration (internal)

The whole combo, when it’s under your team’s direct control.messages:send, messages:bulk, templates:read, templates:create, templates:update.

CLI-driven provisioning

Automated onboarding: connects channels, registers webhooks, verifies.channels:read, channels:connect, webhooks:read, webhooks:manage.

Webhook-based integration

Your backend receives realtime events and inspects delivery history.webhooks:read, webhooks:manage, channels:read.

Knowledge-base sync

Your CMS or docs pipeline publishes documents and assigns them to assistants automatically.knowledge:read, knowledge:write, knowledge:delete, knowledge:assign, assistants:read.

External RAG / search

An external app queries your knowledge base as retrieval for its own LLM.knowledge:read, knowledge:query.

Scheduling — read-only catalog and availability

Your public website or client app shows branches, services, professionals, and available times — no booking.scheduling:branches:read, scheduling:services:read, scheduling:professionals:read, scheduling:availability:read.

Scheduling — full booking flow

Your integration creates, confirms, and cancels appointments end-to-end.scheduling:branches:read, scheduling:services:read, scheduling:professionals:read, scheduling:availability:read, scheduling:appointments:read, scheduling:appointments:create, scheduling:appointments:confirm, scheduling:appointments:cancel.

CRM — reporting and dashboards

A BI tool or dashboard reads the pipeline without ever writing to it.crm:customers:read, crm:tickets:read, crm:tasks:read, crm:notes:read.

CRM — two-way sync, no deletes

Your external CRM or ERP keeps records in step with Keebai. Deletes stay out so a sync bug cannot erase history.crm:customers:read, crm:customers:write, crm:tickets:read, crm:tickets:write, crm:tasks:read, crm:tasks:write, crm:notes:read, crm:notes:write.

CRM — activity logger

A dialer or email tool writes call and email records onto the right ticket, and nothing else.crm:tickets:read, crm:notes:write.

Storefront pricing widget

Your website shows live prices and stock. It never touches customer data.ecommerce:products:read.

Abandoned-cart recovery

Finds pending carts and messages the customer with the recovery link.ecommerce:carts:read, contacts:read, messages:send.

Sales reporting

A BI job pulls closed sales nightly. Read-only, no catalog, no carts.ecommerce:sales:read.

Loyalty terminal

Your point of sale enrolls customers, accrues on purchase, and hands out the wallet card.loyalty:read, loyalty:write.

Loyalty balance display

A kiosk or a customer-facing screen shows the balance and nothing more. Cannot move points or push notifications.loyalty:read.

Assistant provisioning

Your onboarding flow creates an assistant per client and writes its prompt blocks from a template you keep in git.assistants:read, assistants:write.

Prompt auditor

A reviewer reads every assistant’s blocks and their history to check what the bots are told to say. Cannot change a word, and webhook secrets stay masked.assistants:read.

Contact sync

Your CRM or ERP keeps the contact directory in step with Keebai. Deletes stay out so a sync bug cannot erase people.contacts:read, contacts:write.

AI agent over MCP

An agent that answers with your knowledge base, replies on WhatsApp, and logs what it did — without being able to destroy anything.knowledge:query, contacts:read, messages:send, crm:tickets:read, crm:tickets:write, crm:notes:write.

CRM reads are company-wide. A crm:*:read scope returns records from every project in your company, not just the project the token was minted for. Writes stay scoped to the token’s project. See the CRM overview before handing a CRM token to a third party.

Change a token’s scopes

You can’t edit scopes on an existing token. The pattern is:

Mint a new token with the right scopes

From API Keys, click Create API Key and pick the new scopes.

Update your integration

Swap the old token for the new one in your secret manager.

Revoke the old

Once the integration is happily on the new token, revoke the old one.

This pattern gives you zero-downtime rotation.

Get started

Authentication

MCP

SDK

CLI

Agent Skills

Limits

How they’re validated

Catalog

The MCP server uses the same scopes

Scopes are independent from role permissions

Least privilege by example

Transactional backend (1:1 notifications)

Marketing tool / outbound CRM

Template viewer

Template provisioning

Full-stack integration (internal)

CLI-driven provisioning

Webhook-based integration

Knowledge-base sync

External RAG / search

Scheduling — read-only catalog and availability

Scheduling — full booking flow

CRM — reporting and dashboards

CRM — two-way sync, no deletes

CRM — activity logger

Storefront pricing widget

Abandoned-cart recovery

Sales reporting

Loyalty terminal

Loyalty balance display

Assistant provisioning

Prompt auditor

Contact sync

AI agent over MCP

Change a token’s scopes

​How they’re validated

​Catalog

​The MCP server uses the same scopes

​Scopes are independent from role permissions

​Least privilege by example

Transactional backend (1:1 notifications)

Marketing tool / outbound CRM

Template viewer

Template provisioning

Full-stack integration (internal)

CLI-driven provisioning

Webhook-based integration

Knowledge-base sync

External RAG / search

Scheduling — read-only catalog and availability

Scheduling — full booking flow

CRM — reporting and dashboards

CRM — two-way sync, no deletes

CRM — activity logger

Storefront pricing widget

Abandoned-cart recovery

Sales reporting

Loyalty terminal

Loyalty balance display

Assistant provisioning

Prompt auditor

Contact sync

AI agent over MCP

​Change a token’s scopes

How they’re validated

Catalog

The MCP server uses the same scopes

Scopes are independent from role permissions

Least privilege by example

Change a token’s scopes