GuidesJWT authentication

Make authenticated RPC requests

After you bind a public key to a Nodes API key, each RPC request must include both credentials:

  • The Nodes API key in the endpoint URL path.
  • The signed JSON Web Token (JWT) in the Authorization: Bearer <JWT> header.

Copy the HTTP endpoint URL from the Endpoints tab for your Nodes API key. The copied URL includes the API key path. Set the URL and a freshly generated token as environment variables:

$export CONDUIT_RPC_URL='https://[YOUR_RPC_URL]/[YOUR_API_KEY]'
$export JWT='[YOUR_SIGNED_JWT]'

If you need a token, generate a JWT first.

Send a request

These examples call eth_blockNumber and print the JSON-RPC response.

Save the example as request.ts or request.go.

1const rpcURL = process.env.CONDUIT_RPC_URL
2const token = process.env.JWT
3
4if (!rpcURL || !token) {
5  throw new Error('Set CONDUIT_RPC_URL and JWT')
6}
7
8const response = await fetch(rpcURL, {
9  method: 'POST',
10  headers: {
11    'Content-Type': 'application/json',
12    Authorization: `Bearer ${token}`,
13  },
14  body: JSON.stringify({
15    jsonrpc: '2.0',
16    id: 1,
17    method: 'eth_blockNumber',
18    params: [],
19  }),
20})
21
22if (!response.ok) {
23  throw new Error(`RPC request failed: ${response.status} ${await response.text()}`)
24}
25
26console.log(await response.json())

Run the example:

$npm install --save-dev tsx @types/node
$npx tsx request.ts

A successful response contains the latest block number in the result field.

Refresh tokens before they expire

Issue short-lived tokens from your backend and replace them before exp. Never embed the private key or token-generation code in a browser app. If several clients share a token, refresh it early enough that active requests don’t cross the expiration time.

Troubleshoot authentication errors

If Conduit rejects a request, check that:

  • The endpoint URL contains the correct Nodes API key.
  • The Authorization header uses the Bearer <JWT> format.
  • The JWT hasn’t expired.
  • The JWT header’s kid matches the Key ID shown in Conduit.
  • The JWT algorithm matches the algorithm selected for the public key.
  • The public key is enabled and bound to the API key in the endpoint URL.

For other HTTP and JSON-RPC failures, use the RPC error reference.