4 min read
Overview
No matter what kind of add-on you’re creating, you’ll need to understand our provisioning, update, and deprovisioning process. It’s crucial for you to understand when to service a request and when to return a 429 error. In this guide, we’ll dive into the authentication mechanism we use for the process, each one of the steps, and how they relate to what you get paid.
In case you don't want to manually implement the provisioning API, our starter repositories offer a complete and functional implementation of the provisioning API in the language of your preference:
Authentication
All Provisioning/Update APIs below should be protected using HTTP Basic Authentication. You will receive a username and password as part of the Marketplace onboarding process. You can find it in your add-on’s security tab on the Marketplace app:
These credentials are unique to your account--do not share them with anyone. You must also implement authentication against these credentials on your provisioning, update and deprovisioning server.
🚨 If you provision, update or deprovision services without verifying these credentials, you could be the victim of fraud and provide services for which you will not be paid.
With that in mind, let’s dive into each of the steps.
Provisioning
Your API must accept an HTTP POST request with a payload like the one you see below. We will send this after a customer has successfully been charged for your service:
{
"quicknode-id": "9469f6bfc411b1c23f0f3677bcd22b890a4a755273dc2c0ad38559f7e1eb2700",
"endpoint-id": "2c03e048-5778-4944-b804-0de77df9363a",
"wss-url": "wss://long-late-firefly.quiknode.pro/2f568e4df78544629ce9af64bbe3cef9145895f5/",
"http-url": "https://long-late-firefly.quiknode.pro/2f568e4df78544629ce9af64bbe3cef9145895f5/",
"referers": ["quicknode.com"], // may be null as well if none set
"contract_addresses": [],
"chain": "ethereum",
"network": "mainnet",
"plan": "your-plan-slug",
}
This should trigger idempotent provisioning of service on your side based on the quicknode-id. We recommend that at a MINIMUM you store this ID along with the plan being sent in the provision request.
If referers is set, you will need to pass it as a header with each request you make to the customer's endpoint. Additionally, you should definitely store all of these pieces of information.
Note - Any incoming requests that include X-QN-TESTING in the headers are from the QuickNode development team or testing tools.
We expect your response to have the following structure:
{
"status": "success", // or "error"
"dashboard-url": "http://auth.yoursite.com/access/jwt",
"access-url": "http://api.yoursite.com/some-token-here"
}
We will use the access-url to show the customer how they can access the service (for example, if it’s an explorer, graph instance, some kind of index, GraphQL API or, REST API). If you are providing a JSON-RPC method, then simply return access-url as null. We will use the dashboard-url to log the customer into your service with SSO. We have a guide on SSO here.
If responding with error, please be sure to use a non-200 HTTP status code.
Update
In the event that a customer rolls their token, adds or removes a referrer, updates approved contracts for interaction, or changes their plan, we’ll send a PUT request to your update URL that looks like:
{
"quicknode-id": "9469f6bfc411b1c23f0f3677bcd22b890a4a755273dc2c0ad38559f7e1eb2700",
"endpoint-id": "2c03e048-5778-4944-b804-0de77df9363a",
"wss-url": "wss://long-late-firefly.quiknode.pro/2f568e4df78544629ce9af64bbe3cef9145895f5/",
"http-url": "https://long-late-firefly.quiknode.pro/2f568e4df78544629ce9af64bbe3cef9145895f5/",
"referers": ["quicknode.com"], // may be null as well if none set
"contract-addresses": [],
"chain": "ethereum",
"network": "mainnet",
"plan": "new-plan-id"
}
You simply need to respond with:
{
"status": "success" // or "error"
}
Along with the appropriate HTTP status code.
In the case of a plan change, all charges will be pro-rated. For example, if a customer buys a $100 plan on the first of the month and then changes to a $150 plan on the 15th of the month, we would only charge the customer an additional $25, because they already were charged $100. The remaining $50 would be pro-rated for the remaining 15 days to ($150-$100)*(15/30).
Deactivate Endpoint
Since an account can have multiple endpoints under a single plan, we also tell you when an endpoint is turned off by a customer so you don't serve traffic for that endpoint anymore. When this happens, we’ll send a DELETE request to your Deactivate Endpoint URL that looks like:
{
"quicknode-id": "9469f6bfc411b1c23f0f3677bcd22b890a4a755273dc2c0ad38559f7e1eb2700",
"endpoint-id": "2c03e048-5778-4944-b804-0de77df9363a",
"deactivate-at": 876236783468328, // unix timestamp
"chain": "ethereum",
"network": "mainnet"
}
You simply need to respond with:
{
"status": "success" // or "error"
}
Along with the appropriate HTTP status code.
To get a complete list of chains and networks, please see the final section of the How We Proxy RPC Requests for Marketplace Partners guide.
Deprovisioning
When a customer's payment fails (for the last time) or they cancel service, we will send a deprovision DELETE request to your deprovision URL that looks like:
{
"quicknode-id": "9469f6bfc411b1c23f0f3677bcd22b890a4a755273dc2c0ad38559f7e1eb2700",
"endpoint-id": "2c03e048-5778-4944-b804-0de77df9363a",
"deprovision-at": 876236783468328
}
The `deprovision-at` is the time that you should cut service off for customers, in UTC. Please do not turn service off until the deprovision at time has passed since the customer has paid for service up to that time. You should respond with:
{
"status": "success" // or "error"
}
Along with the appropriate HTTP status code.
Conclusion
These steps and information are crucial for a smooth and secure integration into QuickNode Marketplace. We provide some of the tools to ease the development of a secure integration to our partners, but we are happy to answer any other questions you might have!
We <3 Feedback! If you have any feedback or questions on this guide, let us know here! We’d love to hear from you!