LSAT: Authentication and Payments for the Lightning-Native Web

Olaoluwa Osuntokun
March 30, 2020

Today we’re excited to announce the release of our draft of a specification for Lightning Service Authentication Tokens (LSAT). LSAT 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. LSATs 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 LSATs, 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) LSAT reverse proxy which is used in production today by Lightning Loop. Aperture can be used to easily create a new LSAT-aware paid API or service, and even seamlessly upgrade an existing web resource or API to make it LSAT-enabled, creating a portal from the existing web to the new Lightning-native web.

One can view LSATs as a fancy authentication token or cookie. They differ from regular cookies in that they're a cryptographically verifiable bearer credential. An LSAT token encodes all its capabilities within a macaroon which can only be created by the end service provider. The LSAT 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 LSATs 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 LSAT draft specification. The spec itself is open source, and we’re actively accepting contributions!


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 LSAT 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. LSATs enable the creation of a new more global, more private, more developer friendly web.

HTTP + Macaroons + Lightning = LSAT

An LSAT 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 LSAT protocol allows a user to atomically purchase one of these tickets for sats over the Lightning Network. Partial LSATs 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 LSAT can then be converted into a complete LSAT 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 LSAT-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 LSAT 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 LSAT in this very manner to provide a lightweight authentication mechanism for our users.

As LSATs 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 LSATs 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, LSATs 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 LSAT standard, tier upgrades can easily be automated: the user hits a new endpoint to obtain an upgraded LSAT which encodes additional functionality or increased resource access compared to the prior tier. Services can even leverage LSATs for A/B Testing by giving subsets of users distinct LSATs 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 LSAT 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 LSAT 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 LSAT-aware. This initial release of Aperture supports minting for targeted services, LSATs that restrict the path/resource a user can access, expiring LSATs (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.


In this post, we’ve introduced LSAT, a new standard for authentication and paid APIs for the web. LSATs use the Lightning Network for payments, and a combination of HTTP-402 and macaroons for authentication and forgery resistance. The LSAT 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!

About the authorOlaoluwa Osuntokun

Olaoluwa received his B.S and M.S in CS from UCSB. During his graduate studies he focused on the field of applied cryptography, specifically encrypted search. Before he became an active contributor to the Bitcoin open source ecosystem, he spent three consecutive summers as a Software Engineering Intern at Google. These days, his primary focus lies in designing and building private, scalable off-chain blockchain protocols, such as Lightning.

Olaoluwa received his B.S and M.S in CS from UCSB. During his graduate studies he focused on the field of applied cryptography, specifically encrypted search. Before he became an active contributor to the Bitcoin open source ecosystem, he spent three consecutive summers as a Software Engineering Intern at Google. These days, his primary focus lies in designing and building private, scalable off-chain blockchain protocols, such as Lightning.