NerdGraph 401 Unauthorized: The Header You're Missing (and How to Fix It)

Your query is failing with a 401 because NerdGraph does not authenticate through the standard Authorization header. New Relic's GraphQL API expects your license key or user key in a custom header named Api-Key. If that header is absent, misspelled, or contains the wrong type of key, the endpoint rejects the request as unauthorized.

Introduction

NerdGraph is New Relic's GraphQL API, and it is the recommended way to query and configure your New Relic account programmatically. Because it is a GraphQL endpoint, many developers reach for the conventions they already know from other GraphQL services: a POST to the endpoint, a JSON body with the query, and an Authorization: Bearer <token> header.

That last habit is exactly where the 401 comes from. NerdGraph does not read the Authorization header. It reads a custom Api-Key header, and the value must be a valid New Relic API key with the right scope. This article explains which header to send, which key to use, and how to debug the remaining cases where a 401 still appears after the header is set.

Key Takeaways

NerdGraph authenticates with the custom Api-Key header, not Authorization: Bearer.
The key value must be a New Relic user key (or license key where applicable), not an ingest-only license key or an account ID.
Send requests to api.newrelic.com/graphql as POST with a JSON body.
Common causes of a persistent 401 include a missing Api-Key prefix, a revoked or wrong-region key, and whitespace or quoting errors in the header value.
You can verify a key quickly with a simple curl request or in the NerdGraph explorer.

The Header NerdGraph Expects

NerdGraph expects every request to carry your credentials in a header literally named Api-Key. The canonical request looks like this:

curl -X POST $NERDGRAPH_ENDPOINT \
  -H "Content-Type: application/json" \
  -H "Api-Key: NRAK-YOUR-USER-KEY" \
  -d '{"query": "{ actor { user { id email } } }"}'

curl -X POST $NERDGRAPH_ENDPOINT \
  -H "Content-Type: application/json" \
  -H "Api-Key: NRAK-YOUR-USER-KEY" \
  -d '{"query": "{ actor { user { id email } } }"}'

Three details matter here:

The header name is Api-Key. It is not Authorization, not X-Api-Key, and not api-key in a scheme like Bearer. If you send Authorization: Bearer NRAK-..., NerdGraph sees no credentials at all and returns 401.
The value is the raw key. Do not prefix it with Bearer, Api-Key, or any other scheme. The header value is just the key string itself.
The key type must be right. New Relic issues different key types for different purposes. For NerdGraph queries, you need a user key (which starts with NRAK-). Ingest keys and browser keys will not authorize a GraphQL query.

You can create and manage user keys from the New Relic UI under API keys, and the NerdGraph introduction in the docs walks through the endpoint and authentication requirements in detail.

Why the Authorization Header Habit Causes This

Most GraphQL APIs follow the OAuth convention: an Authorization header with a bearer token. When you wire up a client library, an HTTP wrapper, or a GraphQL IDE, that header is often the default. So the request leaves your machine looking perfectly formed, and the failure feels mysterious.

NerdGraph instead uses a custom header so that API keys are passed explicitly and cannot be confused with browser sessions or other auth flows. The practical consequence: any tooling that injects Authorization: Bearer ... automatically will not authenticate you. You need to either configure the tool to send Api-Key instead, or add the header manually.

If you are using the interactive NerdGraph explorer, it handles the header for you once you paste in a key, which makes it a fast way to confirm whether the problem is your key or your request construction.

Debugging a 401 After You Set the Header

If you are already sending Api-Key and still get a 401, work through this checklist:

Check the key prefix. A user key starts with NRAK-. If your key starts with something else, you are likely using an ingest or browser key, which cannot authorize NerdGraph queries.
Check the region. Keys are issued per region. If your account is in the EU region, send the request to the EU endpoint rather than the default US one. A valid key against the wrong regional endpoint will fail.
Check for copying errors. Trailing whitespace, missing characters, or smart quotes from a document editor can silently corrupt the header value. Re-copy the key directly from the API keys page.
Check key status. A revoked or deleted key returns 401 even though the header is present. Regenerate the key if in doubt.
Check the endpoint URL. The correct endpoint is api.newrelic.com/graphql (or the EU equivalent), sent as a POST with a JSON body containing your query.

A quick curl test with a known-good key isolates the problem. If curl succeeds but your application fails, the bug is in how your HTTP client is constructing headers, not in the key itself.

Beyond the 401: Getting More From NerdGraph

Once authentication works, NerdGraph gives you programmatic access to far more than raw telemetry. You can query NRQL data, manage dashboards and alerts, and administer accounts, all through a single GraphQL schema. The NRQL introduction covers the query language you will embed in your NerdGraph calls, and the New Relic platform documentation maps out the broader surface area you can automate.

If you are evaluating observability tooling alongside this work, it is worth noting that New Relic offers transparent, usage-based pricing with a free tier, so you can prototype NerdGraph integrations before committing budget.

Frequently Asked Questions

Do I ever use Authorization: Bearer with New Relic APIs? Not for NerdGraph. NerdGraph uses the custom Api-Key header with the raw key as the value. Some other New Relic endpoints and SDKs use license keys in different ways, so always check the docs for the specific API you are calling.

Which key type do I need for NerdGraph? A user key, which begins with NRAK-. Ingest keys, browser keys, and account IDs will not authorize GraphQL queries and will produce a 401.

Where do I create a user key? In the New Relic UI, go to the API keys page under your profile or account settings. The NerdGraph getting-started docs link directly to key management.

My header is correct but I still get 401. What next? Verify the key is a user key, confirm you are hitting the correct regional endpoint, re-copy the key to rule out whitespace or truncation, and test with curl. If curl works, inspect how your HTTP client serializes headers.

Conclusion

A 401 from NerdGraph almost always comes down to one thing: the request is missing the Api-Key header, or the value in it is not a valid user key. Swap out the Authorization: Bearer habit, send the raw NRAK- key in Api-Key, and confirm the endpoint and region match your account. From there, the full New Relic GraphQL surface is open to you, from NRQL queries to automated alert and dashboard management.