This is a quick high-level explanation as to how ledger-based authorization works in terms of ledgers and their Public Key Infrastructure (PKI) — whether for-pay or gratis — followed up by a more concrete discussion of the actual API to enable this auth flow.
Ledger-based authorization is depicted in the figure below:
Figure 1: Ledger-based authorization
In the model we see two entities:
The entities own and leverage public and private keys which are part of the Public Key Infrastructure (PKI) of the ledger being used (middle):
The ledger (middle) holds records of transactions from u to s.
The service (bottom) checks the ledger for authorization grants: sufficient transactions on the ledger.
The pseudonymous entity known as s (top-left) depicts the service provider, who never discloses their private key (s-private) but publicly distributes the corresponding public-key or ledger-address (s-public). The service provider proves ownership of s-public by providing signatures (s-sig): being able to furnish a signature proves possession of s-private which in turn proves ownership of s-public.
Step (1) is the service provider distributing their s-public: likely embedded in application code. They user u likely doesn’t need to be aware of the particulars of s-public other than having it provided to u’s wallet for transacting.
Step (2) the user u creates a transaction in order to gain access to the service at some payment tier (perhaps free). The transaction includes the user’s public address (u-public) and a signature (u-sig) proving the user in fact consented to the transaction. The transaction has the recipient address–the service provider’s s-public–along with the amount and a timestamp.
The transaction is added to a public ledger and becomes readable by any connected service: it’s readable by anyone.
Step (3) is the user logging into the service and authenticating. Authentication is as simple as signing for the user’s address u-public. The signature u-sig proves whomever furnishes the signature owns u-public as they claim.
That’s it for authentication, as simple as providing a signature.
Step (4) is the service authorizing the user u with address u-public. There could be multiple authorization tiers based on payments received over different time frames. The service checks for tallies of ledger transactions from u-public to s-public–from the user u to the service provider s. The tallies dictate authorization tier allowed.
In step ($) the service provider accesses the ledger to collect fees paid.
That was a brief on ledger-based authorization. For a more detailed look, especially as it concerns US dollars, please see the ledger-based authorization write-up.
You, as a service provider (s in description above), leverage this Remuneration API (dollars/ ethers/ bitcoins) to implement the above authorization workflow. The API is called directly from your back-end and indirectly via your front-end’ s use of pay2my.app widgets or the ledgers.js library.
The Remuneration API is depicted in figure 2 below; it is the HTTP APIs (main orange arrows) in the figure.
Figure 2: Remuneration API as used by “business logic” and “ledgers.js”
The Remuneration API (HTTP APIs) is called directly from business logic back-ends (grey cogs) via HTTP. The API makes available data from ledgers (tables on left). The API abstracts different ledgers–crypto and otherwise–with two simple methods:
These two calls are all that’s needed for our ledger-based authorizations workflow.
The overhide Remuneration API enables the ledger-based authorization flow summarized above.
All remuneration providers expose an identical API contract: just two methods.
At this moment we have the following overhide remuneration providers exposing “live” API documentation: