celestiaorg / celestiaorg/celestia-node

bug: Auth Token Missing from Example Requests in OpenRPC Spec

Open
#4,817 1 comment 0 reactions 0 assignees View on GitHub
enhancement external
Dominant language
Go
Stars
996
Forks
1.1k
Avg merge
1d 6h
Merged PRs (30d)
34

Description

## 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:

```json
{
"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 ` 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
```

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

```bash
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 ` header in every example request for methods with a `perm` tag
2. Use a placeholder like `$CELESTIA_NODE_AUTH_TOKEN` or `` 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 auth `)

## 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)](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`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.