Account & operations

Macaroons

Use macaroons for direct LND access. Use environment-scoped API keys for the Payments API. These credentials have separate permissions and revocation paths. See Access Model.

Protect admin credentials

Exporting means revealing, copying, or downloading a credential outside its protected storage. Hex and base64 are encodings, not encryption. A copied credential retains its permissions. Removing a downloaded file later does not revoke other copies.

Keep privileged credentials for controlled administration. Do not delete node files or recovery material to stop exports. That can make funds unrecoverable. Use the supported node-management workflow with your Voltage advisor when credential replacement is necessary.

Choose the narrowest permissions

Workflow	Starting point	Check before use
Monitoring	Read only	Limit access to the node data your service needs. Read access can expose sensitive financial information.
Receiving invoices	Invoice	Verify that invoice and address operations meet your requirements. This is not a general payment-sending credential.
A specific set of node calls	Custom macaroon	Allow only the required RPC methods or permission groups. Review every write, signing, and credential-management permission.
Node administration	Admin or Super Admin	Reserve for trusted operators and temporary administrative work. Never use as a convenient application default.

The current Voltage Invoice definition for LND 0.17 and later includes invoices:read, invoices:write, address:read, address:write, and onchain:read. Read only includes read permissions across multiple node subsystems. Neither label means the credential is safe to publish. Definitions depend on the node version. Inspect the actual credential and required RPC permissions before deployment.

For custom baking and inspection, use the official LND macaroon guide. Check the node’s LND version and supported connection workflow first. Do not paste privileged credentials into online inspection tools.

Give each integration a dedicated credential. Separate monitoring, invoicing, payment sending, channel operations, signing, and recovery access. A dedicated name alone does not guarantee a separate root key or independent revocation.

Store and use credentials safely

Store macaroons in an approved server-side secret manager. Limit who and what can retrieve them.
Keep them out of browsers, mobile apps, source control, logs, screenshots, tickets, and chat.
Record each credential’s owner, consumers, permissions, root-key relationship, and replacement procedure without recording its secret value.
For REST, send hex in the Grpc-Metadata-Macaroon header. For gRPC, attach hex as macaroon metadata.
Validate TLS and the intended node and network. Follow Configuration.
Restrict network access separately. See Node IP allowlisting.

Understand deletion, revocation, and rotation

Action	Effect
Delete a local export or stored Voltage credential record	Removes that copy or record. This alone does not invalidate credentials already held elsewhere.
Delete an eligible LND root key	Invalidates all macaroons derived from that key, including copies and credentials shared by other integrations.
Bake another macaroon	Creates a credential. This alone does not invalidate earlier credentials.
Rotate a credential	Requires replacing its consumers and invalidating the old authority. Confirm both steps succeeded.

LND supports deleting non-default root keys. Its default root key, ID 0, cannot be deleted through DeleteMacaroonID. A default Admin macaroon cannot be revoked individually through that operation. Node-wide root-key rotation is different: it replaces root keys and invalidates existing macaroons across the node. Voltage does not currently expose that node-wide operation in the dashboard. Coordinate recovery with Voltage because every dependent credential and service may need replacement. See LND root-key deletion for the upstream restriction.

Open the node’s Manage Access > Macaroon Bakery to manage supported credentials. For Read only, Invoice, and BTCPay Server credentials baked on LND 0.17 or later, Revoke deletes the LND root key first. It then removes the stored Voltage record. Support revocation is blocked; Node Wallet offers rotation rather than individual revocation. Legacy credentials sharing root key 8658243 must rotate as a group.

The Macaroon Bakery cannot rotate or revoke Admin or Super Admin. The current dashboard warning describes both as credentials that cannot be rotated or revoked. For Super Admin, that wording describes the bakery limitation, not LND’s capability. LND can delete its non-default root key, invalidating every credential derived from it and breaking existing Lightning Node Connect sessions. Contact your Voltage advisor before attempting that deletion. Do not treat it as a routine self-service recovery step. The stored credential list is not a complete inventory of every exported or externally baked macaroon.

Before revocation or rotation, identify all consumers of the affected root key, including Payments fulfillment and support connections. Coordinate changes with your Voltage advisor. Some rotations invalidate old access before replacement finishes and can interrupt service. Do not assume a failed operation rolled back, or that changing a node password revoked exported macaroons.

If a credential may be exposed

Stop distributing the credential. If node funds may be at risk, restrict node network access to trusted sources immediately. Then contact your Voltage advisor through your established support channel for credential replacement and service recovery. Describe the affected environment, credential type, suspected exposure time, and affected services. Do not send the credential or recovery secrets.

Coordinate credential replacement and revocation with the responsible operators after immediate containment. Verify old access is denied and required services still work. Review node activity and reconcile direct node actions with Payments records.