Authentication Methods for Marketplace Add-Ons

9 min read

Overview

Want to build an add-on but not sure how to manage user access? QuickNode now supports four authentication methods, each designed for different use cases and security requirements. Whether you're building an open public service, need simple access control, or require complex user management, there's an authentication option that fits your needs.

This guide explores the different authentication methods available for QuickNode Marketplace add-ons, Header-Based Authentication, HTTP Basic Auth, traditional Provisioning APIs, and No Authentication. This guide explores each method, helping you choose the best approach for your service based on your specific requirements.

What You Will Learn

The different authentication methods available for QuickNode Marketplace add-ons
The benefits and trade-offs of each method
Implementation examples for each authentication method

What You Will Need

A QuickNode partner account
Familiarity with HTTP requests and responses
Basic understanding of API concepts and Web3 development

QuickNode Partner Account

If you don't have a QuickNode partner account yet, it's easy to get started. After logging in to your QuickNode dashboard, click on the avatar icon on the top left and select the Switch to Partners tab, and then complete the marketplace account application. Approval process for new marketplace partners may take up to 7 business days, however, in general, you can generally expect a response in 1-2 business days.

QuickNode Marketplace Partners Application Form

Ready to Build?

This guide focuses on authentication, but QuickNode offers extensive resources for building add-ons from scratch. Check out the following resources:

Starter Code repositories:

Authentication Methods

The QuickNode Marketplace supports multiple authentication methods to integrate your API, making it easier than ever to onboard without requiring code changes on your end.

Before diving into the details of each method, here's a quick overview of all the authentication options available for QuickNode marketplace add-ons:

Method	Best when…	Key benefit
Header‑Based Auth (any HTTP header)	Your API already expects a header.	Zero code changes. QuickNode forwards the header exactly as provided.
HTTPS Basic Auth	You need a single username/password pair for all Marketplace traffic.	Simple to set up and minor code changes.
No Auth	Your service is meant to be fully public (e.g. Flashbots Protect).	Frictionless for both partner and users.
Custom Provisioning API	You must implement custom endpoints for user lifecycle management.	Full control over customer lifecycle.

Note: QuickNode handles rate limiting for all authentication methods, so you don't need to implement your own rate limiting logic.

1. Header-Based Authentication

This method allows you to use any custom HTTP header for authentication. You can define the header name and the secret value that QuickNode will use to authenticate requests to your API. This option allows direct integration of your existing API without requiring any code changes on your end, provided your API already supports header-based authentication.

Important: Additional HTTP Headers

When QuickNode forwards requests to your API, we automatically include several identification headers alongside your custom authentication header:

X-QUICKNODE-ID: The customer's unique ID
X-INSTANCE-ID: The specific endpoint ID for this request
X-QN-CHAIN: The blockchain network
X-QN-NETWORK: The network environment
X-QN-TESTING: Present during QuickNode QA testing (helps identify test traffic)

For Strict APIs: If your existing API validates incoming headers strictly and rejects requests with unexpected headers, you may need to configure it to accept these additional headers.

If you're interested in joining the QuickNode Marketplace with your API, it's as simple as providing the header name and value during the add-on setup process. Also, our Marketplace team can potentially build the integration for you.

Header-Based Authentication

Implementation Example

Here's a simple example of how to implement Header-Based Auth in your add-on service using Express.js:

Example of Header-Based Auth header
import { Router } from 'express'
const router = Router()

// Middleware to validate custom header
const validateCustomHeader = (req, res, next) => {
    const apiKey = req.headers['x-api-key'] // Your custom header name
    const expectedKey = process.env.CUSTOM_API_KEY
    
    if (!apiKey || apiKey !== expectedKey) {
        return res.status(401).json({ error: 'Unauthorized: Invalid API key' })
    }
    
    next()
}

router.post('/rpc', validateCustomHeader, async (request, response) => {
    // Extract QuickNode headers for enhanced functionality
    const quicknodeId = request.headers['x-quicknode-id']
    const instanceId = request.headers['x-instance-id']
    const chain = request.headers['x-qn-chain']
    const network = request.headers['x-qn-network']
    const isTesting = request.headers['x-qn-testing'] === 'true'
    
    // Process the authenticated request
    const { method, params } = request.body

    // Your service logic here
    const result = processRequest(method, params, { quicknodeId, chain, network, isTesting })

    response.json({
        jsonrpc: '2.0',
        result: result,
        id: request.body.id
    })
})

2. HTTP Basic Auth Protection

HTTP Basic Auth provides a lightweight and secure way to protect your Marketplace add-on endpoints without the need for custom provisioning APIs. When you select this option, QuickNode includes a standard HTTP Basic Auth header in every request forwarded to your add-on's service endpoint.

If you select HTTP Basic Auth protection, requests forwarded to your service endpoint will include a Basic Auth HTTP Header. This header is in the format Authorization: Basic <credentials>, where <credentials> is the Base64 encoding of a username and password joined by a single colon (e.g., username:password). Your add-on service is responsible for validating these credentials with each incoming request.

HTTP Basic Auth

QuickNode securely stores the username and password you provide during the add-on setup and automatically generates the Base64 encoded string for inclusion in the Authorization header.

Example of an Authorization header, where Aladdin is the username and open sesame is the password:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Important: Additional HTTP Headers

When QuickNode forwards requests to your API, we automatically include several identification headers in addition to the Authorization: Basic header:

X-QUICKNODE-ID: The customer's unique ID
X-INSTANCE-ID: The specific endpoint ID for this request
X-QN-CHAIN: The blockchain network
X-QN-NETWORK: The network environment
X-QN-TESTING: Present during QuickNode QA testing (helps identify test traffic)

For Strict APIs: If your existing API validates incoming headers strictly and rejects requests with unexpected headers, you may need to configure it to accept these additional headers.

Implementation Example

Here's a simple example of how to implement HTTP Basic Auth in your add-on service using Express.js:

Example of HTTP Basic Auth header
import { Router } from 'express'
const basicAuth = require('express-basic-auth')
const router = Router()

// Provisioning API is behind basic auth
const authDetails = {}
authDetails[process.env.BASIC_AUTH_USERNAME] = process.env.BASIC_AUTH_PASSWORD
const authInfo = {
	users: authDetails,
	challenge: true,
	unauthorizedResponse: 'Not Authorized',
}

// Apply the basicAuth middleware to your RPC endpoint.
// Any request to '/rpc' will first be authenticated using the provided credentials.
router.post('/rpc', basicAuth(authInfo), async (request, response) => {
	// Extract QuickNode headers for enhanced functionality
    const quicknodeId = request.headers['x-quicknode-id']
    const instanceId = request.headers['x-instance-id']
    const chain = request.headers['x-qn-chain']
    const network = request.headers['x-qn-network']
    const isTesting = request.headers['x-qn-testing'] === 'true'

    // Process the authenticated request
	const { method, params } = req.body

	 // Your service logic here - can use header info for routing/access control
    const result = processRequest(method, params, { quicknodeId, chain, network, isTesting })

    response.json({
        jsonrpc: '2.0',
        result: result,
        id: request.body.id
    })
})

3. Provisioning APIs

Traditional provisioning APIs provide maximum flexibility and control over user management, usage tracking, and access control. This method requires implementing custom endpoints for user lifecycle management. With this approach, QuickNode interacts with a set of APIs you provide to automate the lifecycle of user subscriptions.

Required Endpoints

You need to implement these key endpoints for provisioning APIs:

Endpoint	Description
`/provision`	Creates a new instance of your add-on for a QuickNode user
`/deprovision`	Removes an add-on instance when a user unsubscribes
`/deactivate_endpoint`	Deactivates a specific endpoint associated with your add-on
`/update`	Updates an existing provisioned add-on instance

Security Requirement: You must protect your provisioning APIs with HTTP Basic Auth. QuickNode provides the username and password during add-on setup.

Learn more about how provisioning works for Marketplace Partners in our dedicated guide: How Provisioning Works for Marketplace Partners.

Implementation Example

QuickNode provides starter code in various programming languages to help you get started. Here's an example from our Node.js starter code:

This example demonstrates the /provision endpoint from a QuickNode Marketplace add-on starter template. It handles the creation of new accounts and endpoints when a user subscribes to your add-on. The basicAuth(authInfo) middleware protects this endpoint with HTTP Basic Auth.

Code snippet for a provisioning API
router.post('/provision', basicAuth(authInfo), async (request, response) => {
	const [account, accountCreated] = await models.Account.findOrCreate({
		where: { quicknode_id: request.body['quicknode-id'] },
		defaults: {
			is_test: request.headers['X-QN-TESTING'] === 'true',
			plan: request.body['plan'],
		},
	})
	console.log('Upserted account with id: ' + account.get('id'))

	const [endpoint, endpointCreated] = await models.Endpoint.findOrCreate({
		where: {
			quicknode_id: request.body['endpoint-id'],
			account_id: account.get('id'),
		},
		defaults: {
			is_test: request.headers['X-QN-TESTING'] === 'true',
			plan: request.body['plan'],
			chain: request.body['chain'],
			network: request.body['network'],
			wss_url: request.body['wss-url'],
			http_url: request.body['http-url'],
		},
	})
	console.log('Upserted endpoint with id: ' + endpoint.get('id'))

	var baseUrl = request.protocol + '://' + request.get('host')

	response.json({
		status: 'success',
		// replace below with real URL for sso login
		'dashboard-url': `${baseUrl}/dashboard`,
		'access-url': `${baseUrl}/api`, // Return null if not applicable
	})
})

4. No Authentication

No authentication is perfect for open services that don't require access control or user verification. This option provides the simplest integration path with minimal overhead.

Requests from QuickNode are forwarded directly to your service endpoint without any authentication headers or credentials. Your service receives the raw requests exactly as they come from users.

Implementation Example

Your service simply needs to handle incoming requests without authentication checks:

Example of No Authentication
import { Router } from 'express'
const router = Router()

router.post('/rpc', async (request, response) => {
    // Process the request directly - no auth needed
    const { method, params } = request.body
    
    // Your service logic here
    const result = processRequest(method, params)
    
    response.json({
        jsonrpc: '2.0',
        result: result,
        id: request.body.id
    })
})

Choosing the Right Method

Select your authentication method based on these key considerations:

Choose Custom Headers when you have:

Existing APIs with header-based authentication
Zero tolerance for API modifications

Choose HTTP Basic Auth when you need:

Simple access control for private services
Security without complexity
Service-level authentication (not per-user)
Quick implementation with minimal overhead

Choose Provisioning APIs when you need:

Granular access control and user management
Custom dashboard or user interface
Complex business logic tied to subscriptions

Choose No Authentication when you're building:

Open public services or APIs
Community tools and utilities
Services that benefit from unrestricted access
Simple integrations requiring maximum performance

Conclusion

QuickNode's flexible authentication options make it easier than ever to integrate your services with the marketplace. Basic Auth and Header-Based Auth provide the sweet spot for most existing services, offering security and compatibility without requiring code changes. No authentication enables open services to integrate seamlessly, while traditional provisioning APIs continue to support advanced use cases requiring custom user management.

Ready to build your QuickNode marketplace add-on? Check out the resources below to get started. If you have any questions, feel free to use our dedicated channel on Discord or provide feedback using the form below. Stay up to date with the latest by following us on X and our Telegram announcement channel.

We ❤️ Feedback!

Let us know if you have any feedback or requests for new topics. We'd love to hear from you.

Further Resources

10 Week-length Marketplace Course: Building a JSON-RPC Add-On for Marketplace
Marketplace Partners Page: QuickNode Marketplace Partners
Marketplace Partners Guides: QuickNode Marketplace Guides

Authentication Methods for Marketplace Add-Ons

Overview​

What You Will Learn​

What You Will Need​

Authentication Methods​

1. Header-Based Authentication​

Implementation Example​

2. HTTP Basic Auth Protection​

Implementation Example​

3. Provisioning APIs​

Required Endpoints​

Implementation Example​

4. No Authentication​

Implementation Example​

Choosing the Right Method​

Conclusion​

We ❤️ Feedback!

Further Resources​

Overview

What You Will Learn

What You Will Need

Authentication Methods

1. Header-Based Authentication

Implementation Example

2. HTTP Basic Auth Protection

Implementation Example

3. Provisioning APIs

Required Endpoints

Implementation Example

4. No Authentication

Implementation Example

Choosing the Right Method

Conclusion

Further Resources