This doc contains tutorials on how to use NerdGraph to programmatically manage some New Relic API keys. For general information about New Relic keys, see API keys.
Overview of feature description
You can use the API keys UI to create and manage keys. Alternatively, you can use NerdGraph's ApiAccess
field to programmatically create and manage the following types of keys:
- User keys
- License keys, including:
- General license key (used for APM, infrastructure monitoring, more)
- Browser key (for browser monitoring)
One common use case for this feature is the ability to create and manage license keys to let you rotate keys for security purposes. Note that you can't use this NerdGraph functionality to manage or delete your original license keys; you can only create additional license keys and manage the ones you've created.
Notes about this functionality:
- All mutations can accept multiple keys as arguments, and will return details about successful changes and errors. See examples below for details.
- All mutations (create, update and delete) will result in an
NrAuditEvent
that can be queried for auditing purposes. For details, see Audit events. - Regarding license keys:
- License keys are categorized by NerdGraph as ingest keys. This is because their main use is to allow data ingest.
- You can create up to 1,000 keys of each license key type, which allows for key rotation.
- You can't manage or delete original license keys; you can only create additional license keys and manage keys you've created.
Before using examples
Things to note before using these example queries:
- The examples below use license keys (aka ingest keys), but you can query user keys in similar ways, replacing the ingest-key-specific fields with user-key-specific fields.
- To understand the data structure, we recommend experimenting with queries using the GraphiQL explorer.
- You can also create, view, and delete user keys using the UI.
Create keys
Tip
You can find and generate user keys using the NerdGraph GraphiQL explorer, at the top of that interface.
To create multiple keys (user key or license key) in a single mutation, for multiple accounts and key types. Note that the mutation can return successfully created keys as well as any errors encountered trying to create keys.
Example of creating a key:
mutation {
apiAccessCreateKeys(keys: {ingest: {accountId: YOUR_ACCOUNT_ID, ingestType:
BROWSER, name: "Browser Key", notes: "A note."}}) {
createdKeys {
id
key
name
notes
type
... on ApiAccessIngestKey {
ingestType
}
}
errors {
message
type
... on ApiAccessIngestKeyError {
accountId
errorType
ingestType
}
}
}
}
Results will vary depending on your data. Use the GraphiQL explorer to experiment with mutations and queries.
Here's an example of using this query to create a user key:
Update keys
The update mutation takes the key ID, not the key string, to identify keys.
mutation {
apiAccessUpdateKeys(keys: {ingest: {keyId: KEY_ID, name: "Updated name", notes:
"A new note!"}}) {
updatedKeys {
id
key
type
name
notes
}
errors {
message
}
}
}
Results will vary depending on your data. Use the GraphiQL explorer to experiment with mutations and queries.
Delete keys
The delete mutation takes the key ID, not the key string, to identify keys. Deleted keys will no longer grant access to New Relic systems and will no longer be returned by queries to the API access GraphQL API.
mutation {
apiAccessDeleteKeys(keys: {ingestKeyIds: INGEST_KEY_ID}) {
deletedKeys {
id
}
errors {
message
}
}
}
Results will vary depending on your data. Use the GraphiQL explorer to experiment with mutations and queries.
Query keys
You can access ingest and user keys by querying a single key or all keys, scoped to the actor. If querying for a single key, you must provide the key ID and type (INGEST or USER). Querying for multiple keys is done via a key search, which uses a mandatory types list and an optional scope to filter results. User keys belonging to other users will be obfuscated in the results.
Single key example query:
query {
actor {
apiAccess {
key(id: INGEST_KEY_ID, keyType: INGEST) {
key
name
type
... on ApiAccessIngestKey {
ingestType
}
}
}
}
}
Key search example query:
query { actor { apiAccess { keySearch(query: {types: INGEST, scope: {ingestTypes: BROWSER}}) { keys { name key type ... on ApiAccessIngestKey { ingestType } } } } }}
Results will vary depending on your data. Use the GraphiQL explorer to experiment with mutations and queries.
For more help
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's and and documentation.