Licenses
Most of the Public API is available to every LedgerBee company. A few modules are licensed separately and gated by a per-tenant license — an entitlement the company holds — in addition to the API-key scope. A call to a licensed module succeeds only when both gates pass: the credential carries the required scope, and the company holds the required license.
Scopes and licenses are independent gates
Scope and license answer different questions, and granting one never grants the other.
| Gate | Lives on | Controls | Missing → | details |
|---|---|---|---|---|
| Scope | the API key / OAuth client | which operations the credential may perform | 403 INSUFFICIENT_PERMISSIONS | requiredScopes |
| License | the company (resolved from the credential's tenant) | whether the company has the module at all | 403 LICENSE.REQUIRED | licenseKey |
Scopes are configured per key/client under Marketplace — see Authentication. A license is held by the company and resolved server-side from the credential; it is never set per request.
Licensed modules
These Public API areas require the company to hold a license. The value in
details.licenseKey on a 403 LICENSE.REQUIRED is the license to enable.
| Module | Endpoints | details.licenseKey |
|---|---|---|
| Subscriptions | /v1/subscriptions, /v1/subscriptions/* | Subscription |
| Projects | /v1/projects, /v1/projects/* | Projects |
| Customer Portal — pricing catalogue | /v1/portal/plans, /v1/portal/plans/resolve, /v1/portal/plans/{planId} | CustomerPortal |
| Customer Portal — provisioning & SSO | /v1/portal-sso/provision, /v1/portal-sso/handoff/mint, /v1/portal-sso/sessions/revoke | CustomerPortal |
| MCP (AI agents) | /v1/mcp, /v1/mcp/c/{appCompanyId} | MCP |
Every other endpoint — company, accounts, customers, products, invoices, credit notes, quotes, order confirmations, journal entries, dimensions, VAT codes, meters, document templates, webhooks — is available to every company and needs no license. Each licensed operation also names its license under Required License in the API Reference.
The MCP servers are described in the MCP guide; the
unauthenticated developer endpoint /v1/mcp/developer needs no license. The
licensed Customer Portal flows are covered in
Portal SSO and
Embedded checkout, and subscription
billing in Subscriptions.
When a license is missing
A request to a licensed module the company doesn't hold returns 403 Forbidden
with code: "LICENSE.REQUIRED" and the missing license in details.licenseKey:
Code
Branch on code, never on message. LICENSE.REQUIRED (the company lacks the
module) and INSUFFICIENT_PERMISSIONS (the credential lacks a scope) are both
403 but need different fixes — enable the module versus add the scope. The
full error envelope is in Errors.
Enabling a module
Licenses are managed inside the LedgerBee app, not through the API — a company enables or removes a module with LedgerBee. Once the company holds the license, the same key and scope start working; no credential change is required.