LedgerLou Docs is optimized for desktop.

Please open this page on a device with a wider screen.

LedgerLou Docs
Lou astronaut on a mission

Security model

Scope-driven. Audited. Secure.

Every access — whether via REST API or MCP — runs through the same scope check. No scope, no access. Every action lands in the audit log.

API keyBearer tokenScope-drivenAudit log403 on mismatch

Authentication

REST APIAccess via Bearer-based authentication. The API key is sent as an Authorization: Bearer <key> header. Every route is mapped to a module and checks the corresponding scope.
MCPThe API key is passed via the respective transport or MCP client. Every tool has fixed module scopes and is only executed if the key carries the matching scope.

OAuth MCP clients receive a short-lived access_token (default 30 min) and a rotating refresh_token (default 30 days) on every authorization-code exchange. The refresh token rotates on use; replaying a consumed token revokes the entire token family. Scope widening on refresh is rejected.

Clients that publish a Client ID Metadata Document (CIMD) can pass the document’s HTTPS URL as client_id instead of registering via Dynamic Client Registration. LedgerLou fetches the document once (5 s timeout, 256 KiB cap, SSRF-guarded, validated against a Zod schema), caches it for 24 h, and honors ETag-based conditional re-fetches. The admin superscope and config:* scopes are never granted to CIMD clients — the document’s scope string is intersected with the OAuth-available module scopes.

Scopes

Scopes follow the format module:action. A key carries only the scopes it explicitly needs — no default access to everything.

journalbankkreditorenperiodenauswertungenconfig
:read✓✓✓✓✓✓
:write✓✓✓✓—✓
adminGlobal superscope — covers every module/action combination

✓ REST API and Dashboard only — config:* is not available via MCP.

Operational recommendations

One key per integrationUse a dedicated key per integration with the minimum required scopes. That way any integration can be revoked on its own without affecting others.
Rotate keys regularlyRotate keys on a regular cadence. Disable compromised or obsolete keys immediately.
No scope inflationIf an integration needs more rights, issue a new key — don’t inflate existing scopes. Enforce the principle of least privilege consistently.
Review the audit logEvery action is recorded with key ID, timestamp and scope. Spot unexpected access patterns in the log and respond.

Further reading

Quickstart First integration in a few steps — API key, request, done. REST Endpoints Which route needs which scope — the complete reference. MCP Setup Public overview of MCP access and the scope model.