overhide.io blog
06 Sep 2020
by Jakub Ner

Remuneration API

Ledger-Based Authorization

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:

  • s is the service provider (top-left)
  • u is the user (top-right)

The entities own and leverage public and private keys which are part of the Public Key Infrastructure (PKI) of the ledger being used (middle):

  • s-private and s-public are the service provider’s key pair
  • s-sig is some signature by the service provider proving service provider’s possession of s-private and hence ownership of s-public
  • u-private and u-public are the user’s key pair.
  • u-sig is some signature by the user proving user’s possession of u-private and hence ownership u-public

(please see elsewhere for an understanding of PKI and signatures)

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.

The Remuneration API and ledgers.js

You, as a service provider (s in description above), can leverage the Remuneration API, and its corresponding ledgers.js library, to implement the above authorization workflow.

The Remuneration API is depicted in figure 2 below; it is the HTTP APIs (main green arrow) 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:

  • is-signature-valid: used to verify whether provided signature is valid on a given ledger and whether the signee has transacted on the ledger.
  • get-transactions: used to tally transactions between parties optionally specifying time periods.

These two calls are all that’s needed for our ledger-based authorizations workflow.

Although business logic back-ends access the above API directly (via HTTP calls), this API is accessed through the ledgers.js library from user-facing in-browser login pages. This JavaScript library provides tools and abstractions for dealing with this API, as well as helpers to deal with wallets, signatures, and transactions.

This ledgers.js library is shown above being called by the browser as well as interacting with an in-browser wallet. Users interact solely with their browser login page as well as compatible wallet extensions.

The overhide Remuneration API enables the ledger-based authorization flow summarized above.

All remuneration providers expose an identical API contract: just two methods: this is the static version of the API scrubbed from the overhide Rinkeby Ethereum remuneration provider.

At this moment we have the following overhide remuneration providers exposing “live” API documentation:


US Dollars: