Use NerdGraph to manage license keys and personal API keys

This document contains tutorials on how to use NerdGraph to programmatically create and manage several types of New Relic keys. To build queries and see responses, use our GraphiQL explorer. For more information on our API keys, see API keys.

Feature description

NerdGraph's ApiAccess field can be used to programmatically create and manage the following types of keys:

• Personal API keys
• License keys, including:
  • General license key used for APM
  • Browser license key

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.

General 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.

Some notes about license keys:

• In the context of using NerdGraph, the license keys are referred to as ingest keys.
• This feature allows you to create up to 1,000 keys of each license key type, which allows for key rotation.
• 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.
• License keys created through NerdGraph can't be found in the New Relic UI. They're only queryable via the API.

Some notes about personal API keys:

• In the context of using NerdGraph, personal API keys are referred to as user keys.
• User keys are displayed in various UI locations (for example: the User settings UI page).

The examples below use license keys (ingest keys), but personal API keys (user keys) are queried in similar ways. We recommend you experiment with queries using the GraphiQL explorer. You can also create, view, and delete personal API keys using the UI.

Create keys

You can create multiple keys 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
      accountId
      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.

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