From 4c3e6e10393431f059e3634ddb333aa2c4cc5f9f Mon Sep 17 00:00:00 2001 From: kyangnr Date: Wed, 9 Sep 2026 16:26:34 -0700 Subject: [PATCH 1/2] Make terms consistent --- .../system-identities.mdx | 136 +++++++++--------- 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/src/content/docs/accounts/accounts-billing/new-relic-one-user-management/system-identities.mdx b/src/content/docs/accounts/accounts-billing/new-relic-one-user-management/system-identities.mdx index cbc70564588d..b9509c8c4333 100644 --- a/src/content/docs/accounts/accounts-billing/new-relic-one-user-management/system-identities.mdx +++ b/src/content/docs/accounts/accounts-billing/new-relic-one-user-management/system-identities.mdx @@ -1,6 +1,6 @@ --- -title: System identities -metaDescription: Learn what a system identity is in New Relic, where it is used, and how to create and manage one using NerdGraph. +title: System Identities +metaDescription: Learn what a System Identity is in New Relic, where it is used, and how to create and manage one using NerdGraph. tags: - Accounts - Accounts and billing @@ -9,15 +9,15 @@ freshnessValidatedDate: never translationType: machine --- -A **system identity** is a non-human authenticated actor in New Relic. It represents a service, agent, or automated workload — not a person — and has its own credentials, access model, and lifecycle. System identities authenticate directly to New Relic without requiring a user account, and their actions are audited under the identity itself rather than attributed to a human user. +A **System Identity** is a non-human authenticated actor in New Relic. It represents a service, agent, or automated workload — not a person — and has its own credentials, access model, and lifecycle. System Identities authenticate directly to New Relic without requiring a user account, and their actions are audited under the Identity itself rather than attributed to a human user. - Managing system identities via NerdGraph is available to all organizations. A self-service UI for creating and managing customer-owned system identities is planned for a future release. + Managing System Identities via NerdGraph is available to all organizations. A self-service UI for creating and managing customer-owned System Identities is planned for a future release. -## NR-owned vs. customer-owned system identities [#types] +## NR-owned vs. customer-owned System Identities [#types] -There are two types of system identities: +There are two types of System Identities: @@ -44,18 +44,18 @@ There are two types of system identities:
-NR-owned system identities are provisioned and deleted by New Relic. Customer-owned system identities replace the previous practice of tying automation to an individual user's API key — when that person leaves or rotates their key, the automation breaks. A customer-owned system identity is scoped to the organization, fully audited, and credential rotation is owned by the customer. +NR-owned System Identities are provisioned and deleted by New Relic. Customer-owned System Identities replace the previous practice of tying automation to an individual user's API key — when that person leaves or rotates their key, the automation breaks. A customer-owned System Identity is scoped to the organization, fully audited, and credential rotation is owned by the customer. -## Where system identities are used today [#usage] +## Where System Identities are used today [#usage] -- **Autopilot** — When you set up Autopilot, the onboarding flow automatically creates an NR-owned system identity on your behalf. You do not need to create or manage it directly. -- **Agent Control / New Relic Control** — Each Agent Control installation uses a customer-owned system identity with a non-expiring key-pair credential (created during the guided install) to authenticate with the Fleet Control backend over OpAMP. This is distinct from the 12-hour client-secret credential the UI generates for initial bootstrap — the identity that persists on the host uses a key pair and doesn't expire. -- **Fleet Management** — Fleet Control uses system-level identities to establish trust between Agent Control instances and the Fleet Control service. -- **Helm-based manual path** — The `newrelic-auth-rs` CLI can be used to create and manage system identities for Helm chart deployments outside the guided install flow. +- **Autopilot** — When you set up Autopilot, the onboarding flow automatically creates an NR-owned System Identity on your behalf. You do not need to create or manage it directly. +- **Agent Control / New Relic Control** — Each Agent Control installation uses a customer-owned System Identity with a non-expiring key pair credential (created during the guided install) to authenticate with the Fleet Control backend over OpAMP. This is distinct from the 12-hour client-secret credential the UI generates for initial bootstrap — the Identity that persists on the host uses a key pair and doesn't expire. +- **Fleet Management** — Fleet Control uses System Identities to establish trust between Agent Control instances and the Fleet Control service. +- **Helm-based manual path** — The `newrelic-auth-rs` CLI can be used to create and manage System Identities for Helm chart deployments outside the guided install flow. ## Credentials and token lifetimes [#credentials] -System identities support two credential types. Choose based on your use case: +System Identities support two credential types. Choose based on your use case: @@ -81,42 +81,42 @@ System identities support two credential types. Choose based on your use case: Regardless of credential type, the **OAuth access token** returned after authentication expires in **1 hour**. There is no refresh token — your automation must re-authenticate when the token expires. -For key-pair credentials, a signed JWT assertion must be constructed with a maximum validity of **30 days**. +For key pair credentials, a signed JWT assertion must be constructed with a maximum validity of **30 days**. ## Access model [#access] -System identities use the same group-based access model as users: +System Identities use the same group-based access model as users: -1. A system identity is added to one or more **system identity groups** (these are distinct from user groups and can only contain system identities). +1. A System Identity is added to one or more **System Identity groups** (these are distinct from user groups and can only contain System Identities). 2. Roles are granted to the group at either organization scope or account scope. -3. Every identity in the group inherits all roles granted to that group immediately — and loses them immediately if a grant is removed. +3. Every Identity in the group inherits all roles granted to that group immediately — and loses them immediately if a grant is removed. -Auth Domain Managers can create groups, modify role grants, and remove identities from groups. +Authentication Domain Managers can create groups, modify role grants, and remove Identities from groups. ## End-to-end setup workflow [#workflow] -The following steps walk through the full process of provisioning a customer-owned system identity with access to New Relic: +The following steps walk through the full process of provisioning a customer-owned System Identity with access to New Relic: 1. **[Generate an RSA-4096 key pair](#generate-key-pair)** — recommended for production; skip if using a client secret -2. **[Create the system identity](#create)** — with a key pair or client secret -3. **[Create a system identity group](#create-group)** — a container for role assignments -4. **[Add the identity to the group](#add-to-group)** — so it inherits the group's roles +2. **[Create the System Identity](#create)** — with a key pair or client secret +3. **[Create a System Identity group](#create-group)** — a container for role assignments +4. **[Add the Identity to the group](#add-to-group)** — so it inherits the group's roles 5. **[Grant a role to the group](#grant-role)** — org-scoped or account-scoped 6. **[Authenticate](#authenticate)** — exchange credentials for a short-lived access token -After initial setup, use the [management operations](#manage) to list, update, or delete identities and groups. +After initial setup, use the [management operations](#manage) to list, update, or delete Identities and groups. ## Prerequisites [#prerequisites] - A [New Relic User API Key](/docs/apis/intro-apis/new-relic-api-keys/) to authenticate NerdGraph requests -- **Organization Manager** or **Authentication Domain Manager** role to create system identities and groups +- **Organization Manager** or **Authentication Domain Manager** role to create System Identities and groups - Your New Relic **organization ID** (available in **[one.newrelic.com > Administration](https://one.newrelic.com/admin-portal) > Organization**) ## Generate an RSA-4096 key pair [#generate-key-pair] -If you want to create a system identity with a key-pair credential (recommended for production), generate the key pair first. Skip this step if you plan to use a client secret. +If you want to create a System Identity with a key pair credential (recommended for production), generate the key pair first. Skip this step if you plan to use a client secret. -System identities use **RSA-4096 in PEM format**. During transport, the public key must be **Base64-encoded**. +System Identities use **RSA-4096 in PEM format**. During transport, the public key must be **Base64-encoded**. ```shell # Generate the private key @@ -133,7 +133,7 @@ cat public-key.pem | base64 -b 0 | pbcopy Store the private key securely (for example, in a secrets manager or password vault). You will need it later to sign JWT assertions for authentication. New Relic never stores your private key. -## Create a system identity [#create] +## Create a System Identity [#create] ### With a key pair (recommended) [#create-key-pair] @@ -173,12 +173,12 @@ mutation { ``` - The `clientSecret` is returned **once only**. Copy it immediately — you cannot retrieve it again. The secret expires after 12 hours. If it expires, you must create a new system identity. + The `clientSecret` is returned **once only**. Copy it immediately — you cannot retrieve it again. The secret expires after 12 hours. If it expires, you must create a new System Identity. -## Create a system identity group [#create-group] +## Create a System Identity group [#create-group] -System identity groups are containers for assigning role access to a set of system identities. A new group starts empty with no members and no grants. +System Identity groups are containers for assigning role access to a set of System Identities. A new group starts empty with no members and no grants. ```graphql mutation { @@ -193,9 +193,9 @@ mutation { } ``` -Save the returned `id` — you will use it to add identities and grants. +Save the returned `id` — you will use it to add Identities and grants. -## Add a system identity to a group [#add-to-group] +## Add a System Identity to a group [#add-to-group] ```graphql mutation { @@ -212,11 +212,11 @@ mutation { } ``` -You can add a single identity to multiple groups in one call by including additional IDs in either array. +You can add a single Identity to multiple groups in one call by including additional IDs in either array. -## Remove a system identity from a group [#remove-from-group] +## Remove a System Identity from a group [#remove-from-group] -Removing an identity from a group immediately revokes all role access inherited through that group. +Removing an Identity from a group immediately revokes all role access inherited through that group. ```graphql mutation { @@ -233,9 +233,9 @@ mutation { } ``` -## Grant a role to a system identity group [#grant-role] +## Grant a role to a System Identity group [#grant-role] -Access is granted to a system identity group, not to individual identities. All identities in the group inherit the role immediately. +Access is granted to a System Identity group, not to individual Identities. All Identities in the group inherit the role immediately. ### Organization-scoped grant [#grant-org-scoped] @@ -289,12 +289,12 @@ mutation { ``` - To find the role IDs available in your organization, query `customerAdministration { roles { roles { id name } } }` in NerdGraph. + To find the role IDs available in your organization, query `customerAdministration { roles(filter: { organizationId: { eq: "YOUR_ORG_ID" } }) { items { id name } } }` in NerdGraph. ## Authenticate [#authenticate] -After provisioning, your system identity must exchange its credentials for a short-lived access token (1 hour TTL) to make API calls. +After provisioning, your System Identity must exchange its credentials for a short-lived access token (1 hour TTL) to make API calls. ### Authenticate with a client secret [#auth-client-secret] @@ -358,11 +358,11 @@ For EU-region organizations, use: For JP-region organizations, use: - OAuth token endpoint: `https://system-identity-oauth.service.jp.newrelic.com/oauth2/token` -## Manage system identities [#manage] +## Manage System Identities [#manage] -### List system identities [#list-identities] +### List System Identities [#list-identities] -Query all system identities in your organization: +Query all System Identities in your organization: ```graphql { @@ -381,11 +381,11 @@ Query all system identities in your organization: } ``` -The `type` field returns `NR_OWNED` for identities provisioned by New Relic (such as Autopilot) or `STANDARD` for customer-owned identities. Use `nextCursor` to paginate through results. +The `type` field returns `NR_OWNED` for Identities provisioned by New Relic (such as Autopilot) or `STANDARD` for customer-owned Identities. Use `nextCursor` to paginate through results. -### List system identity groups [#list-groups] +### List System Identity groups [#list-groups] -Query all system identity groups in your organization: +Query all System Identity groups in your organization: ```graphql { @@ -405,7 +405,7 @@ Query all system identity groups in your organization: The `provisionedBy` field returns `"system"` for groups that New Relic manages automatically, or `null` for customer-created groups. Do not modify groups where `provisionedBy` is `"system"`. -### Rename a system identity [#rename] +### Rename a System Identity [#rename] ```graphql mutation { @@ -419,7 +419,7 @@ mutation { } ``` -### Rename a system identity group [#rename-group] +### Rename a System Identity group [#rename-group] ```graphql mutation { @@ -434,9 +434,9 @@ mutation { } ``` -### Revoke a role from a system identity group [#revoke-role] +### Revoke a role from a System Identity group [#revoke-role] -Revoking a role from a group removes that role from all identities in the group immediately. +Revoking a role from a group removes that role from all Identities in the group immediately. **Organization-scoped:** @@ -485,22 +485,22 @@ mutation { } ``` -### Revoke a compromised system identity [#revoke-compromised] +### Revoke a compromised System Identity [#revoke-compromised] -If a system identity's credentials are leaked or a host is compromised, revoke access immediately: +If a System Identity's credentials are leaked or a host is compromised, revoke access immediately: -1. **List all system identities** to find the compromised identity's ID using the [list query](#list-identities). -2. **Delete the compromised identity** using the mutation below. Deletion is immediate — the identity loses all role access and any tokens it has obtained stop working at the next API call. -3. **Create a new system identity** with fresh credentials and add it to the appropriate group. -4. **Update your automation** to use the new identity's credentials. +1. **List all System Identities** to find the compromised Identity's ID using the [list query](#list-identities). +2. **Delete the compromised Identity** using the mutation below. Deletion is immediate — the Identity loses all role access and any tokens it has obtained stop working at the next API call. +3. **Create a new System Identity** with fresh credentials and add it to the appropriate group. +4. **Update your automation** to use the new Identity's credentials. - There is no token revocation endpoint — access tokens issued before deletion remain valid until their 1-hour TTL expires. If you need to minimize this window, remove the identity from all groups first (revoking role access) and then delete it. + There is no token revocation endpoint — access tokens issued before deletion remain valid until their 1-hour TTL expires. If you need to minimize this window, remove the Identity from all groups first (revoking role access) and then delete it. -### Delete a system identity [#delete-identity] +### Delete a System Identity [#delete-identity] -Deleting a system identity is permanent and removes it from all groups it belongs to. The identity loses all inherited role access immediately. +Deleting a System Identity is permanent and removes it from all groups it belongs to. The Identity loses all inherited role access immediately. ```graphql mutation { @@ -511,12 +511,12 @@ mutation { ``` - Deleting a system identity that is actively used by an agent (such as an Agent Control instance) will cause that agent to lose authentication and stop functioning. Ensure the identity is no longer in use before deleting. + Deleting a System Identity that is actively used by an agent (such as an Agent Control instance) will cause that agent to lose authentication and stop functioning. Ensure the Identity is no longer in use before deleting. -### Delete a system identity group [#delete-group] +### Delete a System Identity group [#delete-group] -Deleting a group removes all its role grants. Member identities lose all roles inherited through the group immediately, but the identities themselves are not deleted. +Deleting a group removes all its role grants. Member Identities lose all roles inherited through the group immediately, but the Identities themselves are not deleted. ```graphql mutation { @@ -532,15 +532,15 @@ mutation { ## Current limitations [#limitations] -- **No credential rotation without downtime.** There is no graceful zero-downtime credential rotation — replacing a key-pair identity's public key invalidates the old key immediately. Client secret rotation is not yet supported. +- **No credential rotation without downtime.** There is no graceful zero-downtime credential rotation — replacing a key pair Identity's public key invalidates the old key immediately. Client secret rotation is not yet supported. - **Client secret TTL is fixed at 12 hours.** Configurable TTL (with longer options such as 1 year) is planned for a future release. -- **No self-service UI yet.** Customer-owned system identity management is currently NerdGraph-only. A UI is planned. +- **No self-service UI yet.** Customer-owned System Identity management is currently NerdGraph-only. A UI is planned. - **No refresh token.** Access tokens expire after 1 hour and must be re-requested — there is no token refresh flow. -- **One credential per identity.** Dual-credential support (for zero-downtime rotation) is post-limited preview. +- **One credential per Identity.** Dual-credential support (for zero-downtime rotation) is post-limited preview. ## What's next [#whats-next] -- [Set up Agent Control](/docs/new-relic-control/agent-control/setup) — uses system identities for Kubernetes, Linux, and Windows host management -- [Set up Autopilot](/docs/agentic-ai/autopilot/setup) — system identity is created automatically during setup -- [Terraform: Agent Control](/docs/infrastructure-as-code/terraform/agent-control) — automate Agent Control setup including system identity creation -- [Fleet Control security](/docs/new-relic-control/fleet-control/security) — how system identities fit into the Fleet Control security model +- [Set up Agent Control](/docs/new-relic-control/agent-control/setup) — uses System Identities for Kubernetes, Linux, and Windows host management +- [Set up Autopilot](/docs/agentic-ai/autopilot/setup) — System Identity is created automatically during setup +- [Terraform: Agent Control](/docs/infrastructure-as-code/terraform/agent-control) — automate Agent Control setup including System Identity creation +- [Fleet Control security](/docs/new-relic-control/fleet-control/security) — how System Identities fit into the Fleet Control security model From 1e7f2f2df2b820b369248192e0ace3ac0993a235 Mon Sep 17 00:00:00 2001 From: kyangnr Date: Thu, 10 Sep 2026 10:51:19 -0700 Subject: [PATCH 2/2] Update system-identities.mdx --- .../system-identities.mdx | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/src/content/docs/accounts/accounts-billing/new-relic-one-user-management/system-identities.mdx b/src/content/docs/accounts/accounts-billing/new-relic-one-user-management/system-identities.mdx index b9509c8c4333..2c4de4057f0c 100644 --- a/src/content/docs/accounts/accounts-billing/new-relic-one-user-management/system-identities.mdx +++ b/src/content/docs/accounts/accounts-billing/new-relic-one-user-management/system-identities.mdx @@ -367,13 +367,12 @@ Query all System Identities in your organization: ```graphql { customerAdministration { - systemIdentities(organizationId: "YOUR_ORG_ID") { + systemIdentities(filter: { organizationId: { eq: "YOUR_ORG_ID" } }) { items { id name clientId type - createdAt } nextCursor } @@ -390,12 +389,11 @@ Query all System Identity groups in your organization: ```graphql { customerAdministration { - systemIdentityGroups(organizationId: "YOUR_ORG_ID") { + systemIdentityGroups(filter: { organizationId: { eq: "YOUR_ORG_ID" } }) { items { id name organizationId - provisionedBy } nextCursor } @@ -403,7 +401,7 @@ Query all System Identity groups in your organization: } ``` -The `provisionedBy` field returns `"system"` for groups that New Relic manages automatically, or `null` for customer-created groups. Do not modify groups where `provisionedBy` is `"system"`. +Groups that New Relic provisions for you, such as the group created during Autopilot setup, cannot be renamed or deleted. ### Rename a System Identity [#rename] @@ -526,8 +524,8 @@ mutation { } ``` - - Do not delete groups where `provisionedBy` is `"system"` — these are managed by New Relic and are required for features like Autopilot to function. + + Groups that New Relic provisions are required for features such as Autopilot and cannot be deleted. ## Current limitations [#limitations]