Authentication

Use one Bearer key for Narwhal REST and MCP requests.

Every Narwhal data request requires an API key. Health, OpenAPI, and the documentation UIs remain public.

Get an API key

Create an account with Google or GitHub. A free key is created after sign-in and shown once.

The dashboard shows your signed-in account and setup links. Complete keys are still shown only once.

Store the key safely

The key is returned once when it is issued. Narwhal stores only a one-way verification value, not the key itself, so the same key cannot be shown again.

Keep it in a secret manager or a local environment variable.
Do not commit it, paste it into logs, or place it in a URL.
Do not expose it in browser-side code.

Terminal

export NARWHAL_API_KEY="nw_live_..."

Authenticate a request

Send the key in the HTTP Authorization header using the Bearer scheme. REST and MCP use the same header.

Authenticated REST request

curl --request GET \
  --url https://api.narwhalapi.com/v1/economics/USA/cpi \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

Handle a rejected key

A missing, malformed, inactive, or unknown key returns 401 with code invalid_api_key and a WWW-Authenticate: Bearer header.

Rejected authentication does not consume monthly quota. Use the response's request_id when asking for help; never send the key itself.

Recovery and rotation

Sign in and open the dashboard to rotate or revoke your key. Rotating shows the new key once and keeps the old key working for 24 hours so you can deploy the new one; you can end the old key early. Revoking stops every key at once. The 24-hour grace period covers REST and MCP only; event streams and browser stream tickets require the active key. Streams using the old key close within about 15 seconds; new connections with it are refused, so reconnect with the new key.

If you lose access to the account session, stop using any exposed key and contact Narwhal API for help.

Continue with the quickstart after the key is stored safely.