A Proof-of-Concept that demonstrates how an API Provider can manage access to their Airnode in their backend using the metadata relayed in each Airnode request.
Secrets used on a public blockchain become public. It is important that we avoid sending API secrets over the blockchain while still allowing API providers granular control over user access. This can be achieved through whitelisting an address, similar to IP Address whitelisting, but for wallet/contract addresses.
API providers have the options of off-chain or on-chain whitelisting. Off-chain whitelisting is achieved through Airnode's Relayed Metadata. Each request made to your Airnode will also include some metadata that describes the context of the request being made. This includes the contract, wallet, and chain information that can be checked against your back end for validity. This makes it easy to only respond to requests that are made from addresses provided by paying customers during the subscription process.
More detailed Diagram Here
In this PoC, we take the role of a random number generation API provider that requires (sandbox) credit card payment through our Webstore. Our API subscription order form includes an Eth_Address field. Our Fulfillment Script picks up new orders and creates a user in our Users database in a very typical fashion, but also includes the Eth_Address provided in the Webform.
-
Airnode - Everything you need to run a First-Party Oracle.
-
Webstore - An example Wordpress Woocommerce PoS for API Subscriptions
-
Fulfillment Script - Picks up new orders from Webstore and executes the Authorizer transaction
-
Testing Suite - A dApp for making Airnode requests
These steps should be followed to demonstrate the flow of being denied access, then granting access and having your request responded to.
First clone this repo. Then, start from the root directory of the repo:
1. Start your Order Fulfillment Script
Using our Gitpod will automate this step by spinning up a cloud environment for the whitelisting script.
If you are doing this step locally, please use:
cd whitelister
npm i && node app.js2. Prepare Testing Suite
We will be using the Testing Suite attempt to make a request for a random number. From the /Airnode folder, drag and drop the config/config.json and output/receipt.json files into the respective boxes.
We will be using the GET /randomNumber endpoint.
The /randomNumber endpoint of our API doesn't take any parameters, so the only parameters we need to fill in are the Reserved Params required by Airnode.
- For the "_type" field input
string - For the "_path" field input
randomNumber
Click the "Blockchain Request" button and Connect your Metamask wallet. Be sure you are connected to the Ropsten Network!! Press "Make Request" when you're ready.
After some time (could be minutes depending on the chain), the logs should pick up that the Airnode request failed. This is expected, as we haven't subscribed to the API yet and our request has been denied as unauthorized.
Visit the sandbox API Provider Webstore and add the API Subscription product to your cart and attempt to check out.
You should notice a field for "Eth_add" at the bottom of the checkout form. Here we will add the Sponsor Address for our Testing Suite Contract.
- For the "eth_add" field input
0xe2dB4f54F8FAB66e44386e49aFcB3EF4a87a8787
After checkout you should notice a new user was successfully created in the Fulfillment Script terminal from step 1.
Back in the Testing Suite repeat steps 3 and 4 if necessary and press "Make Request".
This time our Airnode will recognize this request is coming from the address we provided in step 5 and will authorize it and provide us with our random number!
Our goal was to show how easily adjustments could be made to start accepting addresses for whitelisting alongside the authorization methods you are currently using. By deploying your Airnode with a private API key, you can be sure about which requests are coming from your Airnode and that the metadata attached hasn't been tampered with.
This gives API providers the ability to manage authentication of each request to return user-specific data if the use case requires it. An API developer could just as easily add more granularity by providing access based on chain, dApp contract address, or Sponsor Wallet.