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 a beta key

Keys are issued manually during the public beta. Request a beta key and describe the data you want to test.

There is no signup page, dashboard, billing flow, or automated recovery yet.

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

Self-service recovery and rotation are not available during the beta. If a key is lost or exposed, stop using it and contact Narwhal API so the old key can be disabled and a replacement issued.

Continue with the quickstart after the key is stored safely.