Maintaining control over New Relic license and user API keys is critical for ensuring smooth operations and robust security. These keys enable your applications and scripts to communicate with New Relic. However, as organizations grow and teams expand, so does the complexity of managing multiple keys for various environments and purposes. Proper key management ensures tracking which keys are active, understanding their scope, and securely handling their lifecycle.
This guide walks you through the secure management of New Relic license and user keys using NerdGraph with the New Relic UI, or CLI tools.
Types of New Relic Keys
Understanding the different types of keys is crucial before managing them. There are two types of Keys:
Ingest Keys: The only purpose of this key is to get telemetry data into new relic
- License Key: The primary key for ingesting data into New Relic. This 40-character key is account-wide and critical for most telemetry reporting.
- Browser Key: Used exclusively for browser monitoring.
- Mobile App Token: Specifically for mobile monitoring, automatically generated when registering apps.
User API Key: Also known as personal API keys, these are tied to specific users and are primarily used for authenticated access to APIs for querying data, managing configurations for Alerts, Synthetics, Dashboard and more.
Key Management Options
There are two main options to manage keys within New Relic
Option 1 - New Relic UI : Ideal for manual and occasional tasks or on-boarding new team members. You can create and revoke keys with a few clicks.
Option 2 - New Relic’s NerdGraph UI : Ideal for recurring operations for creating, retrieving, and deleting the keys with GraphQL UI query builder.
Option 3 - New Relic CLI: Perfect for automating workflows and managing keys programmatically.
Accessing API keys page New Relic UI
The API keys page in New Relic UI is especially useful for one-time tasks or when onboarding new team members.
Accessing NerdGraph UI in New Relic UI
If you prefer a visual approach, New Relic’s UI offers an intuitive interface to view, create, and revoke keys.
The NerdGraph UI is especially useful for recurring tasks or to create the graphQL queries using the NerdGraph’s graphQL explorer. This screen also provides an option to quickly generate curl or CLI commands for New Relic CLI
Prerequisites
- User Key: Required to access NerdGraph.
Refer to the video below to access the NerdGraph app
Automating Key Management with New Relic CLI
If you prefer working with CLI tools, New Relic provides full support for programmatic key management using NerdGraph via the newrelic CLI. This approach is ideal for key management from a secure sandbox, automation workflows, and CI/CD pipelines.
Prerequisites
- New Relic CLI: Install the New Relic CLI. Refer to the official documentation
- User Key: Required to access NerdGraph.
For all of these queries, you will need the API key ID. The key ID can be accessed simply by going to the API keys UI. Refer to the screenshot below and follow the steps
Here are some examples of querying, creating and deleting your API keys with sample query template
Querying Keys
Retrieving key details is straightforward using the CLI with NerdGraph. Below are simplified examples with CLI commands:
These queries retrieve details like the key name, type, and associated notes.
Ingest Key
NEW_RELIC_API_KEY=INSERT_API_KEY_HERE newrelic nerdgraph query '
query {
actor {
apiAccess {
key(
id: "INGEST_API_KEY_ID"
keyType: INGEST
) {
key
name
type
... on ApiAccessIngestKey {
id
notes
}
}
}
}
}'
Once you run the above command, you should get an output similar to the screenshot below
Note: If you are in the EU region, all you need to add is NEW_RELIC_REGION=eu before the command
This method is useful for fetching existing license or user keys.
USER Key
To fetch USER API keys, use the query below:
NEW_RELIC_API_KEY=INSERT_API_KEY_HERE newrelic nerdgraph query '{
actor {
apiAccess {
key(
id: "USER_API_KEY_ID"
keyType: USER
) {
key
name
type
... on ApiAccessUserKey {
id
notes
}
}
}
}
}
Query All keys from an account
NerdGraph also offers an easy way to query and retrieve all the keys associated with your account. You can filter these keys by account, License Key type (such as Ingest or Browser), or even by specific users using their User IDs.
NEW_RELIC_REGION=us NEW_RELIC_API_KEY=NRAK-3JK50C7DF2CGXR33HV71LF6X4K9 newrelic nerdgraph query '{
actor {
user {
name
}
apiAccess {
keySearch(query: {types: INGEST, scope: {accountIds: YOUR_ACCOUNT_ID}}) {
count
nextCursor
keys {
... on ApiAccessKey {
id
name
key
type
}
}
}
}
}
}'
Creating Keys
The process for creating keys depends on the type of key you need. Following are the examples for creating both User keys and Ingest keys respectively
Ingest Key
For creating INGEST License keys, the only difference is to specify the ingestType parameter without USER_ID
NEW_RELIC_REGION=us NEW_RELIC_API_KEY=INSERT_API_KEY_HERE newrelic nerdgraph query 'mutation {
apiAccessCreateKeys(
keys: {ingest:
{
accountId: YOUR_ACCOUNT_ID, ingestType: LICENSE,
name: "nerdgraph ingest create test", notes: "INGEST Key create test with nerdgraph"}}
) {
createdKeys {
id
key
name
notes
type
createdAt
}
errors {
message
type
}
}
}'
User Key
When creating USER API Keys, ensure you specify the correct ACCOUNT_ID and USER_ID, especially in multi-account and multi-user environments.
NEW_RELIC_REGION=us NEW_RELIC_API_KEY=INSERT_API_KEY_HERE newrelic nerdgraph query 'mutation {
apiAccessCreateKeys(
keys: {user:
{
accountId: YOUR_ACCOUNT_ID, userId: YOUR_USER_ID
name: "nerdgraph test 2", notes: "USER Key create test with nerdgraph"
}
}
) {
createdKeys {
id
key
name
notes
type
createdAt
}
errors {
message
type
}
}
}'Deleting Keys
You can delete an API key for either a USER or INGEST using the same query, with just one small adjustment. The key difference lies in the keys parameter, simply switch between ingestKeyIds and userKeyIds, depending on the type of key you wish to remove.
Below is the NerdGraph query to delete an INGEST API key:
NEW_RELIC_REGION=us NEW_RELIC_API_KEY=INSERT_API_KEY_HERE newrelic nerdgraph
query 'mutation {
apiAccessDeleteKeys(
keys: {ingestKeyIds: "INGEST_API_KEY_ID"}
) {
deletedKeys {
id
}
errors {
message
... on ApiAccessKeyError {
message
type
}
}
}
}'
For deleting a User Key :
NEW_RELIC_REGION=us NEW_RELIC_API_KEY=INSERT_API_KEY_HERE newrelic nerdgraph query 'mutation {
apiAccessDeleteKeys(
keys: {userKeyIds: "USER_API_KEY_ID"}
) {
deletedKeys {
id
}
errors {
message
... on ApiAccessKeyError {
message
type
}
}
}
}'
Key Security Best Practices
Keeping keys secure is fundamental. Follow these simple practices:
- Regularly rotate keys, particularly for production environments.
- Store keys in a secure vault or secret management tool (e.g., HashiCorp Vault, AWS Secrets Manager).
- Audit key activity regularly to ensure no unusual patterns.
- Apply the principle of least privilege, granting only necessary access.
- Revoke unused or stale keys promptly to reduce vulnerabilities.
Avoid Common Mistakes:
- Don’t use long-lived keys without rotation.
- Avoid embedding keys in code repositories or configuration files.
- Never grant global permissions to all keys.
Summary
By effectively managing your New Relic keys, you can secure data, streamline workflows, and reduce operational risks. Whether using the CLI for automation or the UI for ad hoc tasks, New Relic offers flexible tools to meet your team’s specific needs. Ensure your observability strategy is secure by regularly reviewing, rotating, and revoking keys as needed.
Take the next step today:
- Rotate any stale or forgotten keys.
- Rotate any keys provisioned to inactive users.
- Use the New Relic CLI to simplify routine tasks.
- Check out New Relic’s documentation for additional details on key management.
The views expressed on this blog are those of the author and do not necessarily reflect the views of New Relic. Any solutions offered by the author are environment-specific and not part of the commercial solutions or support offered by New Relic. Please join us exclusively at the Explorers Hub (discuss.newrelic.com) for questions and support related to this blog post. This blog may contain links to content on third-party sites. By providing such links, New Relic does not adopt, guarantee, approve or endorse the information, views or products available on such sites.
