Copy page

Use cases

Run Lelemon for your customers with subaccounts

You sell a service built on Lelemon. Each of your customers gets a subaccount: its own agents, pipelines, cases, numbers and keys, isolated from the rest. You keep the tools in one place and share them with every subaccount, you fix how many conversations each one may have, and a single webhook endpoint tells you what happens in all of them.

Who it is for. Software platforms, agencies and franchisors that run agents for many customers. Scopes. Listed above. A subaccount key cannot exceed the scopes of the key that creates it.

1. When your customer signs up, create the subaccount with your own id as externalRef and an Idempotency-Key.
2. Lelemon answers with the sub_ id. A second subaccount with the same externalRef is a 409 external_ref_conflict.
3. Any /v2 route acts on the subaccount when you add the header. The key does not change, only the organization.
4. A subaccount is a full organization, isolated from your other subaccounts. One that is not yours answers 404.
5. You create a tool once in your organization and share it. Each subaccount grants it to its own agents.
6. When an agent of a subaccount uses the shared tool, your backend receives a call signed with your secret and Lelemon-Subaccount-Id, so it knows which customer is asking.
7. One webhook endpoint with scope customers receives the events of all subaccounts. Each carries customerId, the sub_ id it belongs to.

Code
Your platform key
  |- actions.create(sharedWithSubaccounts)      one place for the tool
  |- mcpServers.create(sharedWithSubaccounts)   one place for the server
  |- subaccounts.create (one per customer)
  |      '- Lelemon-Subaccount: sub_...  ->  agents, pipelines, cases of that customer
  |- budgets.create(scope: subaccount)          the monthly cap, enforced
  '- webhookEndpoints.create(scope: customers)  events of every subaccount, with customerId

The script is in examples/use-cases/platform-subaccounts.

0. Set up

Code
import { Lelemon } from '@lelemon-ai/sdk';

const lelemon = new Lelemon({ apiKey: process.env.LELEMON_API_KEY });

1. Share an action with every subaccount

Create the action once with sharedWithSubaccounts: true. Your endpoint is yours: a variable of Lelemon (subaccount.id) tells it which customer is asking, and Lelemon fills it, not the model. A floor is the least approval any subaccount can run the action with; a subaccount can be stricter, never looser.

Code
action {"id":"act_4uQao29MeSRDwnQm98ymB0","sharedWithSubaccounts":true}
    floor {"mode":"when","condition":{"param":"sku","op":"eq","value":"RESTRICTED"},"approvers":[{"type":"role","value":"owner"}],"expiresInMinutes":1440,"automatedDecision":false}

2. Share an MCP server

Connect an MCP server of yours once. Its tools become available to every subaccount agent, with the credentials kept on your side.

Code
mcp server {"id":"mcp_6w5NPeUTIijdv38ds4Hy9C","status":"connected","shared":true,"tools":["mtl_64bepNDEJhXykm9RMrCmnL get_store_hours"]}

The server must be a public Streamable HTTP MCP server. The call asks it for its tools right away. See Actions and MCP.

3. Create a subaccount per customer

externalRef is your own id for the customer, so you can find the subaccount from your database.

Code
subaccount {"id":"sub_4E6vmnn5aCcP6tx7NLmQGF","externalRef":"franchise-mvxa5tb0-1"}

To give the customer direct access, POST /v2/subaccounts/{id}/api-keys issues a key that sees only that subaccount. See Run Lelemon for your customers.

4. Provision the subaccount and use the shared tools

Any route acts on a subaccount when you send the Lelemon-Subaccount header; the SDK does it with withSubaccount. Create the agent and the pipeline of the customer with the same instructions you use for everyone. The shared tools show up in the tool list of the agent with sharedByPlatform: true; grant the ones the customer needs.

Code
actions []
    shared tools ["mtl_64bepNDEJhXykm9RMrCmnL get_store_hours","act_4uQao29MeSRDwnQm98ymB0 get_stock_mvxa5tb0"]
    agent {"id":"agt_49tWojD6RAPxVKzppe3vjD","status":"active","ready":true}

The subaccount does not list shared actions in GET /v2/actions: it reaches them through the tools of its agent, and cannot change or delete them.

5. Cap the conversations of a subaccount

A budget caps the conversations per month of the organization, a subaccount, an agent or a contact. With enforcement: "stop", a message that would open a conversation past the limit answers 402 budget_exceeded and the agent stops opening conversations until the month resets. At alertPercent the event budget.threshold_reached fires once.

Code
budget {"id":"bgt_4kw1BXHwbkPSAdPDyW2EVH","scope":"subaccount","limit":250,"used":0,"state":"ok"}

6. Receive the events of every subaccount

An endpoint with scope: "customers" receives the events of all your subaccounts; each one carries customerId, the sub_ id it belongs to. With scope: "self" it receives only those of the platform organization.

Code
event {"type":"message.created","customerId":"sub_4E6vmnn5aCcP6tx7NLmQGF"}

7. Read the usage of all subaccounts

Bill your customers from the usage: turns, messages and tokens per day, agent, model or subaccount.

Notes

• A budget goes away with DELETE /v2/budgets/{id}, and PATCH /v2/budgets/{id} changes its limit.

What you see in the dashboard

• Subaccounts: one per customer, with its agents, cases and keys, and the budget with its state (ok, alert, limit_reached).
• Actions and MCP servers: the shared ones marked as shared by the platform.
• Usage: the consumption by subaccount for the month.

What's next

• Run Lelemon for your customers: direct keys, templates and limits.
• Track usage and cap conversations.
• Approve agent actions: the floor in action.