L402

Lightning API keys (L402) are Macaroons that include a payment hash. For the L402 to be valid, it must be presented together with the preimage corresponding to the payment hash.

Lightning API keys (L402) leverage the capabilities of Macaroons and the programmatic characteristics of the Lightning Network to create a mechanism that allows distributed systems to authenticate a user and payment receipt. This authentication occurs without requiring access to a central database of users or invoices.

L402 are a cornerstone to building metered APIs for the machine-to-machine economy, without logins, e-mail addresses or passwords.

An L402 is a Macaroon together with the preimage of a Lightning Network payment. The Macaroon is transmitted to the user over HTTP together with a Lightning invoice and contains the payment hash of the invoice as a caveat.

To be a valid L402, the user needs to present two pieces of information:

• The partial L402, being the Macaroon including the payment hash

• The preimage, which can be obtained by paying the Lightning invoice

As the payment hash is a hash of the preimage, and as the preimage can only be obtained through paying the Lightning invoice in full, it is easy for anyone with the root key to verify:

• That the L402 was issued by the appropriate authority

• That the L402 carries the relevant capabilities

• That the Lightning invoice has been paid

secret,id12345678id,api.domain.com,your macaroon
payment_hash=1107feb30b42fd1a1648c9862006452a8092baa3b62fc474cb43bf42066a0b06
HMAC(secret,4c4ab7a4f7a9,api.domain.com,your macaroon)
preimage=79852a0791225dee00be0a6cf31a1619782c21d35995e118bfc74ad812174035

L402 specification

To make for a valid L402, a Macaroon must adhere to the following characteristics:

Version - A version allows for an iterative macaroon design.

identifier: version = 0

User Identifier - A unique user identifier allows services to track users across distinct macaroons serving useful in the context of service level metering. A user identifier of 32 random bytes is used instead of the macaroon’s identifier because the latter can be revoked, e.g., in the case of a service tier upgrade.

identifier: user_id = fed74b3ef24820f440601eff5bfb42bef4d615c4948cec8aca3cb15bd23f1013

Payment Hash - A payment hash links an invoice’s payment request to the macaroon. Once the payment request is fulfilled, the payer receives its corresponding preimage as proof of payment. This proof can then be provided along with the macaroon to ensure an L402 has been paid for without checking whether the invoice has been fulfilled.

identifier: payment_hash = 163102a9c88fa4ec9ac9937b6f070bc3e27249a81ad7a05f398ac5d7d16f7bea

Caveats

There is no limit to what caveats you may define for your service. For Lightning Labs services, three types of caveats are used, which are covered below. Each caveat consists of a key and value pair, separated by an equal (=) sign.

Target Services

The caveat ‘services’ lists which services a L402 is authorized to access. This can be a comma separated list of multiple services, as well as their tier. Tiers allow for separate levels of access, with the basic tier being 0.

In this example the L402 is authorized to access Lightning Loop at tier 0:

caveats: services = lightning_loop:0

Service Capabilities

Each service can be restricted in its capabilities. These caveats have ‘_capabilities’ amended to the service name, followed by a comma separated list of capabilities that the holder of the L402 is allowed to access. If this caveat is not present, the holder has full access to the service. If multiple caveats of this service capability exist in the same L402, each caveat must be more restrictive than the previous one.

In this example the bearer of the L402 is authorized to access both Loop Out and Loop In:

caveats: lightning_loop_capabilities = loop_out,loop_in

Service Constraints

Each service capability can be further constrained. This is recorded as a separate caveat beginning with the service capability. Similar to capabilities, multiple constraints may be present in a L402, but each constraint needs to be more restrictive than the previous.

In the following example the user is allowed to Loop out two million satoshis per month only:

caveats: loop_out_monthly_volume_sats = 2000000

L402 Verification

In verifying the L402, the server requires the root key with which the original Macaroon was created. This allows the server to verify, line by line, caveat by caveat, that the Macaroon was issued by the appropriate authority and that each caveat was properly amended.

Finally, the preimage is verified against the payment hash to ensure that all outstanding invoices have been paid.

Learn how the L402 is obtained in Pool

Get Aperture