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 |
| Meters | /v1/meters/subscriptions, /v1/meters/{meterId}/subscriptions | Subscription |
| Projects | /v1/projects, /v1/projects/* | Projects |
| Customer Portal — provisioning & SSO | /v1/portal-sso/provision, /v1/portal-sso/handoff/mint, /v1/portal-sso/sessions/revoke | CustomerPortal |
Metered usage is part of the Subscriptions module — a usage-billed price
resolves against Subscription too.
Checkout is license-free: the catalogue reads (/v1/portal/plans,
/v1/portal/plans/resolve, /v1/portal/plans/{planId}) and
/v1/portal-checkout/vouch answer for any tenant, gated by the API key and its
scopes alone. CustomerPortal governs portal access — the provisioning and
SSO routes above.
Every other REST endpoint — company, accounts, customers, products, invoices, credit notes, quotes, order confirmations, journal entries, dimensions, VAT codes, 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. MCP is the one surface the table above does not describe, because it gates per tool rather than per endpoint.
MCP itself needs no license. Every company can list and call the read and the
write tools, gated by the grant's scopes and, for write tools, by the company's
MCP permissions. A tool that reads a licensed module declares that module's
license on itself; the tool table in the MCP guide names each one
under Also requires. A call to such a tool without the license fails as an
MCP protocol error, so branch on that rather than on a 403 LICENSE.REQUIRED.
The unauthenticated developer endpoint /v1/mcp/developer needs no license
either.
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.