---
title: NerdGraph tutorial: Manage API keys
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/use-nerdgraph-manage-license-keys-user-keys
---

This doc contains tutorials on how to use [NerdGraph](https://docs.newrelic.com/docs/introduction-new-relic-graphql) to programmatically manage some New Relic API keys: the license key, the browser key, and the user key. For general information about our keys, see [API keys](https://docs.newrelic.com/docs/apis/get-started/intro-apis/types-new-relic-api-keys).

## Overview of feature description [#terms]

You can use the [API keys UI](https://one.newrelic.com/launcher/api-keys-ui.api-keys-launcher) to create and manage keys. Alternatively, you can use [NerdGraph](https://docs.newrelic.com/docs/introduction-new-relic-graphql)'s `ApiAccess` field to programmatically create and manage the following types of keys:

-   [User keys](https://docs.newrelic.com/docs/apis/get-started/intro-apis/types-new-relic-api-keys#personal-api-key), required for using NerdGraph
-   Data ingest keys, including:

    -   The license key: required for the ingest of most data to New Relic, except for browser monitoring data and mobile monitoring data
    -   [Browser key](https://docs.newrelic.com/docs/browser/new-relic-browser/configuration/copy-browser-monitoring-license-key-app-id): required for the ingest of browser monitoring data

One common use case for this feature is the ability to rotate keys for security purposes. Note that you can't use this NerdGraph functionality to delete the license key or browser key that was originally created with an account; those original keys can't be deleted. 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](https://docs.newrelic.com/docs/insights/use-insights-ui/manage-account-data/query-account-audit-logs-nrauditevent).
-   Regarding ingest keys:
    -   License and Browser 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 ingest key type, which allows for key rotation.
    -   You can't manage or delete original account ingest keys but you can contact New Relic support to rotate these; you can only create additional ingest or user keys and manage keys you've created.

## Before using examples [#before-examples]

Things to note before using these example queries:

-   To understand the data structure, we recommend experimenting with queries using the [GraphiQL explorer](https://api.newrelic.com/graphiql).
-   You can also [create, view, and delete user keys using the UI.](https://docs.newrelic.com/docs/apis/get-started/intro-apis/types-new-relic-api-keys#personal-api-key)

## Create keys

> #### 💡 TIP
>
> You can find and generate user keys using the [NerdGraph GraphQL explorer](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/#explorer), at the top of that interface.

To create multiple keys (user key or ingest 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:

```graphql
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](https://api.newrelic.com/graphiql) to experiment with mutations and queries.

Here's an example of using this query to create a [user key](https://docs.newrelic.com/docs/apis/get-started/intro-apis/types-new-relic-api-keys#user-api-key):

**Create a user key**

To create a [user key](https://docs.newrelic.com/docs/apis/get-started/intro-apis/types-new-relic-api-keys#user-api-key), you'd change the above query slightly, in the `keys` section:

````graphql
mutation {
  apiAccessCreateKeys(
    keys: { 
      user: { 
        accountId: YOUR_ACCOUNT_ID, 
        userId: YOUR_USER_ID 
      }
    }
  ) {
    createdKeys {
      id
      key
      name
      notes
      type
      ... on ApiAccessIngestKey {
        ingestType
      }
    }
    errors {
      message
      type
      ... on ApiAccessIngestKeyError {
        accountId
        errorType
        ingestType
      }
    }
  }
}
```

````

## Update keys

The update mutation takes the key ID, not the key string, to identify keys.

```graphql
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](https://api.newrelic.com/graphiql) 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.

```graphql
mutation {
  apiAccessDeleteKeys(keys: { ingestKeyIds: INGEST_KEY_ID }) {
    deletedKeys {
      id
    }
    errors {
      message
    }
  }
}
```

Results will vary depending on your data. Use the [GraphiQL explorer](https://api.newrelic.com/graphiql) 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:

```graphql
query {
  actor {
    apiAccess {
      key(id: "INGEST_KEY_ID", keyType: INGEST) {
        key
        name
        type
        ... on ApiAccessIngestKey {
          ingestType
        }
      }
    }
  }
}
```

Key search example query:

```graphql
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](https://api.newrelic.com/graphiql) to experiment with mutations and queries.