Today we’re excited to announce the release of our draft of a specification for Lightning Service Authentication Tokens (L402). L402 is a new protocol standard for authentication and paid APIs (using the Internet’s preferred currency: sats!) developed by Lightning Labs which leverages the widely underused HTTP 402 (payment required) status code. L402s can serve both as authentication, as well as a payment mechanism (one can view it as a ticket of sorts) for paid APIs. By leveraging L402s, a service or business is able to offer a new tier of paid APIs that sits between free and subscription: metered, with no login, email or passwords required! Alongside this specification, we’re also releasing Aperture, our implementation of an HTTP-402 (Payment Required) L402 reverse proxy which is used in production today by Lightning Loop. Aperture can be used to easily create a new L402-aware paid API or service, and even seamlessly upgrade an existing web resource or API to make it L402-enabled, creating a portal from the existing web to the new Lightning-native web.

One can view L402s as a fancy authentication token or cookie. They differ from regular cookies in that they're a cryptographically verifiable bearer credential. An L402 token encodes all its capabilities within a macaroon which can only be created by the end service provider. The L402 specification uses a combination of HTTP as well as the Lightning Network to create a seamless end-to-end payment+authentication flow for the next-generation of paid APIs built on top of the Lightning Network.

In the remainder of this blog post, we'll explore the motivation, lineage, and workflow of L402s at a high level. We’ll also examine Aperture to see how it’s used today in production by Lightning Loop, and explore some of its initial features. For readers that are interested in more details, we encourage developers and other interested parties to check out the full L402 draft specification. The spec itself is open source, and we’re actively accepting contributions!

L402

The Forgotten HTTP Error Code

HTTP as we know it today uses a number of error codes to allow developers to easily consume APIs or resources created by users on the web. As an example, the well known 200 OK error code indicates a successful HTTP response. The 404 Not Found is sent when a client attempts to access a page or resource that couldn’t be found by the server. A large number of other error codes exist, with some more commonly used than others. One error code which has widely been underutilized is: 402 Payment Required. As the name entails, this code is returned when a client attempts to access a resource that they haven't paid for yet. In most versions of the HTTP specification, this code is marked as being "reserved for future use". Many speculate that it was intended to be used by some sort of digital cash or micropayment scheme, which didn't yet exist at the time of the initial HTTP specification drafting.

However, several decades later, we do have a widely used digital cash system: Bitcoin! On top of that, a new network oriented around micropayments has also arisen: the Lightning Network. Early in the lifetime of Lightning Labs, we were drawn to the potential for paid metered APIs enabled by the Lightning Network. We'd solved the payment portion with LN itself, the next challenge was to create a protocol that would be easy to drop into existing APIs in an easy and extensible manner. Our solution to this is the L402 protocol.

Authentication and API Payments in a Lightning-Native Web

Lightning has the potential to serve as the de facto payment method to access services and resources on the web. In this new web, rather than a user being tracked across the web with invisible pixels to serve invasive ads, or users needing to give away their emails subjecting themselves to a lifetime of spam and tracking, what if a user were able to pay for a service and in the process obtain a ticket/receipt which can be used for future authentication and access?

In this new web, email addresses and passwords are a thing of the past. Instead cryptographic bearer credentials are purchased and presented by users to access services and resources. In this new web, credit cards no longer serve as a gatekeeper to all the amazing experiences that have been created on the web. L402s enable the creation of a new more global, more private, more developer friendly web.

HTTP + Macaroons + Lightning = L402

An L402 is essentially a ticket obtained over Lightning for a particular service or resource. The ticket itself encodes what resource it's able to access (and potentially much more!). It can be copied, or given to a friend so they can access that same resource. It can also be attenuated to provide a friend access to a slightly weaker version of that resource (able to stream video at only 480p as an example). On the other end, services can mint special tickets for particular users, rotate, upgrade, and even revoke the tickets.

The tickets themselves are actually macaroons. Macaroons are a flexible standard for API credentials which are already used by lnd as its default authentication mechanism. The L402 protocol allows a user to atomically purchase one of these tickets for sats over the Lightning Network. Partial L402s are served over HTTP (or HTTP/2) when a user attempts to access a resource that requires payment (402 Payment Required) along with a Lightning invoice. This partial L402 can then be converted into a complete L402 by paying the invoice, and obtaining the payment pre-image (the invoice pays to a payment hash: payment_hash = sha256(pre_image)).

With proper integration at end clients, Lightning wallets, mobile applications, browsers (and extensions), the above flow has potential to be even more seamless than the credit card flow users are accustomed to today. It's also more private as the server doesn't need to know who paid for the ticket, only that it was successfully paid for. For a glimpse at how this new L402-aware web can look like, check out this demo created by Oliver Gugger (one of our Infrastructure Engineers) which leverages Joule to create a seamless experience for a user seeking to obtain information about the “best” nodes on the Lightning Network.

Example Applications and Use Cases

The L402 standard enables a number of new use cases, pricing models, and applications to be built, all using the Lightning Network as a primary money rail. As the standard is also defined over HTTP/2, it can be naturally extended to also support gating access to existing gRPC services. This is rather powerful as it enables a strong decoupling of authentication and payment logic from application logic. Today Lightning Loop uses L402 in this very manner to provide a lightweight authentication mechanism for our users.

As L402s leverage the Lightning Network for its payment capabilities, they also enable the easy creation of metered APIs. A metered API is one where the user is able to pay for the target resource or service as they go rather than needing to commit to a subscription up front. Developers can use L402s to create applications that charge users on an ongoing basis for resources like compute, file hosting, or just raw disk space. If the user stops paying, then the resource can be suspended, collected, and re-allocated for another paying user. Once again, as the standard supports gRPC which supports bi-directional streaming APIs, one could even create a metered streaming video or audio service as well!

Additionally, L402s also enable innovation at the API architecture level. One example is automated tier upgrades. Many APIs typically offer several tiers which allow users to gain access to more or additional resources as they climb up the ladder. Typically, a user must manually navigate a web-page to request an upgrade to a higher tier, or downgrade to a lower tier. With the L402 standard, tier upgrades can easily be automated: the user hits a new endpoint to obtain an upgraded L402 which encodes additional functionality or increased resource access compared to the prior tier. Services can even leverage L402s for A/B Testing by giving subsets of users distinct L402s which when submitted to the service, render a slightly different version of the target resource or service.

Aperture: Your Portal to the Lightning-Native Web

Excited to give the L402 protocol a spin and develop the next generation of Lightning-native web services? Well you’re in luck as we’re also releasing the code for Aperture, our implementation of an L402 aware reverse-proxy which is used in our production systems today. Aperture sits between an API server or web resource and the web itself, seamlessly handling the authentication protocol, macaroon minting and verification, along with payment verification. Using a simple YAML-based config developers can easily create or upgrade an existing web service to be L402-aware. This initial release of Aperture supports minting for targeted services, L402s that restrict the path/resource a user can access, expiring L402s (access to resources for just 1 day as an example), proxying REST and gRPC calls, and it even natively supports exposing services over Tor! The default storage backend for Aperture is etcd a reliable distributed key-value store, which is used as the backbone for many projects such as Kubernetes.

We plan to continue developing Aperture over the coming months, add more features, and generalize its deployment in order to make it more widely usable. We’ve also populated the issue tracker with some low hanging fruit, and some longer term goals, for aspiring contributors to dive into.

Conclusion

In this post, we’ve introduced L402, a new standard for authentication and paid APIs for the web. L402s use the Lightning Network for payments, and a combination of HTTP-402 and macaroons for authentication and forgery resistance. The L402 protocol gives us a glimpse into a Lightning-Native web that is more global, private and extensible. We encourage the community to review our recently published specification and also give Aperture a spin as well. We look forward to all the amazing things developers will build with this new standard and our supporting tooling!