Skip to main content

Auth & Access

One FastNear API key works across the RPC and API endpoints. Keep the auth model simple: use the same credential everywhere and send it either as a Bearer header or an apiKey query parameter.

Get a key in FastNear Dashboard.

Live example pages also support Copy example URL for sharing prefilled requests. Shared example URLs run automatically on load whenever they include operation state, and saved API keys and tokens are never included in those public docs URLs.

If you only need the rule​

  • One FastNear API key works across RPC and API endpoints.
  • Set FASTNEAR_API_KEY in your shell, runtime, or secret manager.
  • Prefer Authorization: Bearer ${FASTNEAR_API_KEY} for production backends.
  • Use ?apiKey=${FASTNEAR_API_KEY} when headers are awkward or you are doing quick curl/debug work.
  • Agents and automations should keep the key in env vars or a secret manager, not in browser storage.

Choose the auth form​

FormBest forNotes
Authorization: Bearer ${FASTNEAR_API_KEY}production backends, workers, automations, and proxiesBest default. Keeps credentials out of copied URLs and most URL logs.
?apiKey=${FASTNEAR_API_KEY}simple curl, one-off debugging, systems that cannot set headers easilyValid, but the key may end up in shell history, logs, analytics, or copied links.

If you control the client, use the header form.

Authorization header example​

: "${FASTNEAR_API_KEY:?Set FASTNEAR_API_KEY in your shell before running this example.}"

curl "https://rpc.mainnet.fastnear.com" \
  -H "Authorization: Bearer $FASTNEAR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"method":"block","params":{"finality":"final"},"id":1,"jsonrpc":"2.0"}'

?apiKey= query parameter example​

: "${FASTNEAR_API_KEY:?Set FASTNEAR_API_KEY in your shell before running this example.}"

curl "https://rpc.mainnet.fastnear.com?apiKey=$FASTNEAR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"method":"block","params":{"finality":"final"},"id":1,"jsonrpc":"2.0"}'

Where this applies​

  • RPC Reference uses the shared FastNear key model on both the regular and archival hosts.
  • API families reuse the same key shape across the REST surfaces.
  • The docs UI can forward a saved FastNear key for supported pages, but that browser storage behavior is a docs convenience, not a production pattern.

For agent and automation runtimes, use Auth for Agents.

Production defaults​

Use these defaults unless you have a specific reason not to:

  • keep the key in an env var or secret manager
  • inject it at the backend, worker, or proxy layer
  • prefer the Bearer header over the query parameter
  • rotate the key if it leaks into a prompt, URL, or debug log

Common failure modes​

The request works without a key in one context but not another​

That usually means you moved from public traffic to a higher-limit or authenticated path. Add the same FastNear key you use elsewhere.

I switched from regular RPC to archival RPC​

Use the same FastNear key and the same header or query-param transport on both hosts. Only the retention profile changes.

My key is showing up in logs​

Switch to the Authorization header if you are currently using ?apiKey=. URLs tend to travel through more logging and observability systems.

The docs UI worked, but my backend does not​

Do not rely on browser storage behavior from the docs UI. Production backends should inject credentials explicitly.

I am building an agent or automation​

Use Auth for Agents for the runtime posture. Browser localStorage is a docs convenience, not an agent secret store.