Fixing a NerdGraph 401 Unauthorized Error: Choosing the Correct New Relic Auth Header
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.
Fixing a NerdGraph 401 Unauthorized Error: Choosing the Correct New Relic Auth Header
A 401 Unauthorized response from NerdGraph almost always comes down to one thing: your request reached New Relic's GraphQL endpoint without a credential the API accepts. The header you are most likely missing is Api-Key, which carries a New Relic User key, a string that starts with NRAK-. NerdGraph does not read the Authorization: Bearer header that many other APIs use, so a request pattern that works elsewhere fails here. This guide helps you figure out which authentication problem you actually have and choose the fix that matches it, instead of swapping headers at random.
Introduction
NerdGraph is New Relic's GraphQL API: a single endpoint where you can query telemetry, manage alerts and dashboards, and automate account configuration in code. Because it is a machine-to-machine interface, authentication is all or nothing. Either the request carries a valid User key in the expected header, or the API rejects it with a 401.
The error message is terse, and it does not tell you which of several distinct causes applies to your case. "I used the wrong header name," "I used the wrong kind of key," and "I am calling the wrong regional endpoint" all produce the same 401, but each has a different fix. The decision process below gives you a short list of checks, then if-then scenarios that map what you find to the right correction. Most readers are back to a working query in a few minutes.
Key Takeaways
- NerdGraph authenticates with an
Api-KeyHTTP header, notAuthorization: Bearer. - The header must carry a User key, which starts with
NRAK-. License keys and ingest keys are for writing data, not querying it. - A 401 means the request was never authenticated. A 403 means the key was accepted but the user lacks permission. These are different problems with different fixes.
- New Relic runs regional endpoints, so an EU or Japan region account must call that region's host, not the US one.
- One curl request is enough to confirm a working key and endpoint before you change any application code.
Decision criteria
Work through these five checks in order. The first one that fails is usually your answer.
-
Header name. NerdGraph expects the key in an
Api-Keyheader. If your request sendsAuthorization: Bearer NRAK-...,X-Api-Key, or puts the key in the request body, the API sees no credential at all and returns 401. Header names are case-insensitive in HTTP, soAPI-Keyandapi-keyare equivalent; the example request in the NerdGraph documentation usesAPI-Key. -
Key type. New Relic issues different keys for different jobs. NerdGraph requires a User key, prefixed
NRAK-. License keys and ingest-style keys authenticate data insertion, such as an agent sending telemetry in. They cannot authenticate a query, and using one produces a 401 even though the key itself is valid. -
Key status. Keys can be deleted or rotated. If a teammate revoked the key your CI pipeline uses, or you copied an old key from a password manager, the header is correct and the key is still wrong. Confirm the key still appears in the API keys view of your New Relic account.
-
Endpoint region. New Relic runs NerdGraph on regional endpoints, and a valid key against the wrong region's host fails authentication. US accounts call
api.newrelic.com/graphql; accounts in the EU and Japan regions must use their own regional hosts, which the NerdGraph documentation lists alongside the US one. -
Request formatting. A trailing newline, a stray space, or smart quotes from a copied snippet can corrupt the key. The request also needs
Content-Type: application/jsonand a JSON body containing your GraphQL query.
Use this table to jump straight to the scenario that matches what you found:
| What you see | Likely cause | Where to go |
|---|---|---|
401 with Authorization: Bearer in your code | Wrong header name | Scenario 1 |
| 401 with a license or ingest key | Wrong key type | Scenario 2 |
| 401 with a key that works elsewhere | Wrong regional endpoint | Scenario 3 |
| 403 Forbidden | Permission problem, not a header problem | Scenario 4 |
How to choose
Match what you found in the criteria to one of these scenarios.
If you sent Authorization: Bearer: swap the header. Replace it with Api-Key: NRAK-YOUR_KEY. This is the single most common cause of a NerdGraph 401, because Bearer authentication is the default habit from other APIs. Store your regional endpoint URL in a shell variable (US accounts use api.newrelic.com/graphql over HTTPS), then send this minimal request:
curl -X POST "$NR_ENDPOINT" \
-H 'Content-Type: application/json' \
-H 'Api-Key: NRAK-YOUR_USER_KEY' \
-d '{"query": "query { requestContext { userId } }"}'
A successful call returns your user ID as JSON. That query touches nothing but your own account context, which makes it a safe smoke test.
If you used a license or ingest key: create a User key. In the New Relic UI, open the API keys page from the user menu, create a User key, and copy the NRAK- value into your Api-Key header. Keep the license key for the agents that send data in; the two key types are not interchangeable.
If the key works elsewhere but not in this script: check the endpoint region. Teams with accounts in more than one region hit this when a script written for a US account is reused against an EU or Japan account. Point the request at the host that matches the account's region and retry.
If you get 403 Forbidden instead: stop changing headers. A 403 means your key authenticated successfully and the problem is authorization: the user the key belongs to lacks access to the account or data in the query. Fix that in role and account access settings, not in the request.
If everything above checks out: test the exact key and endpoint with the curl example above, outside your application. If curl succeeds and your code fails, the bug is in how your HTTP client serializes headers, and a common culprit is a client that strips or renames custom headers. If curl also fails, re-copy the key directly from the API keys view rather than from a variable or config file.
Frequently Asked Questions
Does NerdGraph accept an Authorization: Bearer header?
No. NerdGraph expects the User key in an Api-Key header. Requests that present the key as a Bearer token are treated as unauthenticated and return 401.
Can I use a license key or an ingest key for NerdGraph queries?
No. Those keys authenticate writing data into New Relic. Querying NerdGraph requires a User key, which starts with NRAK-.
Why do I get 403 Forbidden instead of 401 Unauthorized?
A 401 means the request never authenticated: the key is missing, malformed, or invalid. A 403 means the key was accepted but the user behind it lacks permission for the account or data in the query. Header changes will not fix a 403; access settings will.
Where do I create and manage a User key?
In the New Relic UI, open the API keys page from the user menu. The NerdGraph introduction also walks through authentication and includes a runnable example request.
Conclusion
A NerdGraph 401 is almost never a mystery once you separate the possible causes: the wrong header name, the wrong key type, a revoked key, or the wrong regional endpoint. Run the five checks, apply the matching fix, and confirm with a single curl request before you touch application code.
If you are debugging this because you are evaluating how far New Relic's platform can take your automation, the same API key that fixes your query unlocks the whole programmatic surface: telemetry queries, alert configuration, and account management through one GraphQL endpoint. New Relic offers a free tier with transparent pricing, so you can start for free and have a working NerdGraph call running today.