New Relic API Authentication: Methods & Best Practices (2026)

Authentication overview

New Relic provides various APIs to interact with its observability platform, including data ingestion, querying, and configuration management. Authentication secures these interactions, ensuring that API requests are legitimate and authorized. The primary mechanism for authenticating with the New Relic API involves the use of API keys, which serve as tokens that grant specific permissions to access New Relic resources. These keys are typically passed in the HTTP X-Api-Key header or as a bearer token, depending on the specific API endpoint being accessed.

The system is designed to allow fine-grained control over access, with different types of API keys providing distinct levels of permission. This approach aligns with the principle of least privilege, where credentials only possess the necessary permissions to perform their intended functions. Properly managing these keys is crucial for maintaining the security and integrity of your New Relic data and environment.

Supported authentication methods

New Relic APIs primarily utilize API keys for authentication. Different types of keys are designed for specific purposes, offering varying scopes of access. Understanding which key to use for a particular API call is essential for both functionality and security.

API Key Types

• User API Keys: These keys are associated with a specific user and inherit that user's permissions within New Relic. They are generally used for programmatic access that mimics user actions, such as managing alerts or dashboards. User keys are suitable for scripts or applications that require a broad range of actions consistent with a human user's capabilities.
• NerdGraph API Keys: Specifically designed for the NerdGraph API, which is New Relic's GraphQL API. These keys are used for complex queries and mutations across various New Relic data sources. NerdGraph keys often have broader read/write capabilities within the GraphQL schema.
• Insights Insert API Keys: Used for sending custom event data to New Relic Insights. These keys grant permission to ingest data but typically do not allow querying or configuration changes. They are ideal for applications that generate telemetry and need to push it into New Relic.
• License Keys: Historically used for agents to report data. While still relevant for some agent configurations, for newer API interactions, more specific API keys (like Insights Insert keys) are often preferred or required. A license key is primarily for connecting agents to your New Relic account.
• Admin API Keys: Provide broad administrative access, similar to a superuser. These keys should be handled with extreme care due to their extensive permissions, which include managing accounts, users, and various New Relic entities.

Authentication Headers

Most New Relic API requests require the API key to be sent in an HTTP header. The specific header can vary:

• For many REST API endpoints, the key is provided in the X-Api-Key header.
• For the NerdGraph API, the key is typically sent in the Authorization header using the Bearer scheme (e.g., Authorization: Bearer YOUR_NERDGRAPH_API_KEY).

Referencing the official New Relic API introduction to authentication provides specific header requirements for different API endpoints.

Authentication Methods Summary

Getting your credentials

To obtain API keys for New Relic, you typically navigate through the New Relic UI. The process varies slightly depending on the type of key you need.

Generating User and Admin API Keys

1. Log in to your New Relic account.
2. Navigate to Account settings > API keys (or similar path, which may vary with UI updates).
3. Look for options to generate new keys. For User API keys, you might need to select a specific user context or generate a key that inherits a user's role. Admin API keys are usually distinct options due to their elevated privileges.
4. Follow the prompts to name your key and configure any available permissions or expiry settings.
5. Once generated, the key will be displayed. Copy it immediately as it often cannot be retrieved again after leaving the page for security reasons.

Generating NerdGraph API Keys

NerdGraph API keys are typically generated in a dedicated section:

1. Access your New Relic account.
2. Go to API keys or a section specifically for the NerdGraph API.
3. Select the option to create a new NerdGraph key.
4. Assign appropriate scopes or permissions to the key, ensuring it has only the necessary access for your application's needs.
5. Generate and securely store the key.

Generating Insights Insert API Keys

For ingesting data into New Relic Insights:

1. In your New Relic account, navigate to Insights > Manage data > API keys.
2. Select + Insert Key to generate a new key.
3. Name the key and note its value. This key will be used to send custom events to New Relic.

Always consult the New Relic documentation on generating API keys for the most current instructions, as UI paths and options can be updated.

Authenticated request example

This example demonstrates how to make an authenticated request to the New Relic NerdGraph API using a User API key. The request queries for a list of accounts.

curl -X POST 'https://api.newrelic.com/graphql'
     -H 'Content-Type: application/json'
     -H 'API-Key: YOUR_USER_API_KEY'
     -d '{
           "query": "{\n  actor {\n    accounts {\n      id\n      name\n    }\n  }\n}"
         }'

In this example:

• https://api.newrelic.com/graphql is the endpoint for the NerdGraph API.
• Content-Type: application/json specifies the request body format.
• API-Key: YOUR_USER_API_KEY is the header where your User API key is placed to authenticate the request. Replace YOUR_USER_API_KEY with your actual key.
• The -d flag contains the GraphQL query as a JSON string.

For other New Relic REST API endpoints, the header might be X-Api-Key instead of API-Key, and the request body structure would follow REST principles (e.g., JSON payload for creation/update, URL parameters for retrieval).

Security best practices

Securing your New Relic API keys is paramount to protect your observability data and prevent unauthorized access to your account. Adhering to established security practices minimizes risks.

1. Principle of Least Privilege

Grant API keys only the minimum necessary permissions required for their intended function. For instance, if an application only needs to ingest data, provide it with an Insights Insert API key, not an Admin API key. Regularly review and adjust permissions as application needs evolve.

2. Secure Storage of API Keys

Never hardcode API keys directly into your application's source code. Instead, store them in secure environments:

• Environment Variables: A common method for local development and deployment.
• Secret Management Services: For production environments, utilize dedicated secret management solutions like AWS Secrets Manager, Google Secret Manager, Azure Key Vault, or HashiCorp Vault. These services encrypt keys at rest and in transit, provide audit trails, and enable centralized management. The use of robust secret management is a critical aspect of API security, as detailed in Google Cloud's Secret Manager overview.
• Configuration Files: If using configuration files, ensure they are not committed to version control systems and are protected with appropriate file system permissions.

3. Key Rotation

Periodically rotate your API keys. This practice reduces the window of opportunity for a compromised key to be exploited. Establish a rotation schedule (e.g., every 90 days) and have a clear process for updating keys in all applications that use them. New Relic supports key regeneration, which invalidates the old key immediately.

4. Restrict Network Access

If possible, configure firewall rules or network access controls to restrict API calls to New Relic from specific IP addresses or ranges. This adds an extra layer of defense, ensuring that even if a key is compromised, it can only be used from trusted network locations.

5. Monitoring and Auditing

Utilize New Relic's own monitoring capabilities (e.g., audit logs) to track API key usage. Look for unusual access patterns, excessive failed authentication attempts, or activity from unexpected geographical locations. Promptly investigate any suspicious activity.

6. Secure Communication Channels

All communication with New Relic API endpoints should occur over HTTPS (TLS). This encrypts data in transit, protecting API keys and sensitive payloads from eavesdropping. New Relic enforces HTTPS for all its API endpoints, aligning with industry standards for secure web communication, as specified by organizations like the World Wide Web Consortium (W3C).

7. Incident Response Plan

Have a clear incident response plan in place for dealing with compromised API keys. This plan should include steps for revoking the compromised key, generating a new one, identifying the breach's root cause, and assessing potential impacts.