Macaroons
3 min
Macaroons are LND-native credentials for direct node access. They are separate from Voltage team permissions, Payments API keys, and Infrastructure API keys.
Why they matter
Anyone with a node endpoint and a usable macaroon can access the node according to that macaroon's permissions. Access is enforced by LND and is separate from Payments API permissions.
Treat exported macaroons as secrets: Possession of a usable macaroon can authorize node actions without a Payments API key.
Common macaroon types
- Privileged macaroon: broad access. Can perform sensitive actions, including spending funds, according to its permissions.
- Read-only: can view node data but should not spend.
- Invoice: can create or manage invoice-related flows without general spend authority.
- Custom baked macaroons: permissions depend on what was baked into the macaroon. A custom macaroon may be narrow, or it may include permissions that allow funds movement.
Interface authentication
For REST, encode the macaroon as hex and send it in the Grpc-Metadata-Macaroon header.
For gRPC, encode the macaroon as hex and attach it as macaroon metadata. Store every macaroon as a secret according to its permissions.
Best practices
- Give each integration the narrowest macaroon it needs.
- Avoid using admin macaroons in application code.
- Keep read-only monitoring credentials separate from payment, wallet, channel, and administrative credentials.
- Store macaroons in protected server-side secret storage. Do not place them in client applications, source control, logs, screenshots, tickets, or shared notes.
- Stop using any macaroon that is no longer needed or may have been exposed, then follow the current replacement and incident-response process.
For detailed LND commands and permission syntax, use the official LND macaroon documentation: https://docs.lightning.engineering/lightning-network-tools/lnd/macaroons