bug: Auth Token Missing from Example Requests in OpenRPC Spec

[jcstein]

Summary

The generated openrpc.json spec (which powers the https://docs.celestia.org/build/rpc/node-api/) correctly lists the required permission level for each RPC method (e.g. perms: write for blob.Submit), but the example requests do not include the Authorization header. An integrator copying the example request verbatim will get an auth error with no indication of what's missing.

How to Reproduce

1. Go to https://docs.celestia.org/build/rpc/node-api/ and look at blob.Submit
2. Note that the method page does say perms: write — so the permission level is documented
3. Look at the example request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "blob.Submit",
  "params": [
    [
      {
        "namespace": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAMJ/xGlNMdE=",
        "data": "z8QyNztv...",
        "share_version": 0,
        "commitment": "aHlbp+J9yub6hw/uhK6dP8hBLR2mFy78XNRRdLf2794=",
        "index": -1
      }
    ],
    {
      "gas_price": 0.002,
      "is_gas_price_set": true,
      "max_gas_price": 0.4,
      "gas": 142225,
      "tx_priority": 1,
      "key_name": "my_celes_key",
      "signer_address": "celestia1pjcmwj8w6hyr2c4wehakc5g8cfs36aysgucx66",
      "fee_granter_address": "celestia1hakc56ax66ypjcmwj8w6hyr2c4g8cfs3wesguc"
    }
  ]
}

4. Note there is no Authorization: Bearer <token> header shown anywhere in the example
5. Copy-paste this example into a curl call — it fails with an auth error

Expected Behavior

Every example request for a method that requires authentication should include the auth header. For example, the blob.Submit example should show something like:

Authorization: Bearer <token>

alongside the JSON-RPC body, or include a curl example like:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CELESTIA_NODE_AUTH_TOKEN" \
  -d '{ "id": 1, "jsonrpc": "2.0", "method": "blob.Submit", "params": [...] }' \
  http://localhost:26658

The examples should be copy-paste-able and actually work.

Impact

This came up while onboarding an integration partner. They saw the permission level listed on the method, but followed the example request as-is — which doesn't include auth — and hit errors at runtime. The gap between "we tell you auth is required" and "we show you an example without auth" is confusing and slows down integrators.

For someone building against the spec, the examples are the first thing they reach for. If the example doesn't work out of the box, it undermines trust in the docs.

Suggested Fix

Update the spec generation (or the docs site rendering) to:

1. Include an Authorization: Bearer <token> header in every example request for methods with a perm tag
2. Use a placeholder like $CELESTIA_NODE_AUTH_TOKEN or <your-auth-token> to make it clear a token is needed
3. Optionally add a brief note next to each example linking to how to generate a token at the appropriate permission level (celestia <node-type> auth <perm-level>)

Additional Context

• The permission level metadata itself is present in the spec — this is specifically about the example requests not reflecting it
• The [RPC CLI tutorial](https://docs.celestia.org/developers/node-tutorial) covers token generation, but the examples in the spec itself should be self-contained enough to not silently fail

Labels

bug, documentation, api

[Sushil-19]

I’ve opened a PR addressing this issue: #4818

The change updates the OpenRPC generator so that methods with permission metadata automatically include a note indicating that requests must include the Authorization: Bearer <token> header.

This makes the authentication requirement explicit in the generated OpenRPC spec for all methods with read, write, or admin permissions, helping prevent confusion when users copy request examples and encounter authorization errors.

Happy to adjust the approach if maintainers prefer the auth requirement to be reflected differently in the spec or examples.