New Relic User Management API Guide

Auth method: API Key (User API Key passed as header)

Setup steps

1. Log in to New Relic and navigate to the API Keys UI at one.newrelic.com > (user menu) > API keys.
2. Create a User API Key (type: USER) associated with your account.
3. Include the key in all NerdGraph requests as the HTTP header: Api-Key: <YOUR_USER_API_KEY>.
4. For SCIM provisioning, generate a SCIM bearer token from the Authentication domain settings page in New Relic (one.newrelic.com > Administration > Authentication domains).
5. Use the SCIM bearer token as Authorization: Bearer <SCIM_TOKEN> for all SCIM API calls.

Required scopes

List users in an authentication domain

• Method: POST
• URL: https://api.newrelic.com/graphql
• Watch out for: Pagination uses nextCursor; pass it as cursor in subsequent calls. Returns max 500 users per page.

Request example

{ customerAdministration { users(cursor: null, authenticationDomainId: "DOMAIN_ID") { nextCursor items { id name email userType { displayName } } } } }

Response example

{ "data": { "customerAdministration": { "users": { "nextCursor": "abc123", "items": [{ "id": "1234567", "name": "Jane Doe", "email": "jane@example.com", "userType": { "displayName": "Full platform" } }] } } } }

Create user

• Method: POST
• URL: https://api.newrelic.com/graphql
• Watch out for: User is created but not added to any group/role by default. A separate userManagementAddUsersToGroups mutation is required to grant account access.

Request example

mutation { userManagementCreateUser(createUserOptions: { name: "Jane Doe", email: "jane@example.com", authenticationDomainId: "DOMAIN_ID", userType: FULL_PLATFORM_USER_TIER }) { createdUser { id name email } } }

Response example

{ "data": { "userManagementCreateUser": { "createdUser": { "id": "1234567", "name": "Jane Doe", "email": "jane@example.com" } } } }

Update user

• Method: POST
• URL: https://api.newrelic.com/graphql
• Watch out for: Cannot change authenticationDomainId or email via this mutation. Email changes require the user to update their own profile or SCIM re-provisioning.

Request example

mutation { userManagementUpdateUser(updateUserOptions: { id: "1234567", userType: CORE_USER_TIER, name: "Jane Smith" }) { user { id name userType { displayName } } } }

Response example

{ "data": { "userManagementUpdateUser": { "user": { "id": "1234567", "name": "Jane Smith", "userType": { "displayName": "Core" } } } } }

Delete user

• Method: POST
• URL: https://api.newrelic.com/graphql
• Watch out for: Deletion is immediate and irreversible. The user loses all access instantly. Billing stops at the next billing cycle.

Request example

mutation { userManagementDeleteUser(deleteUserOptions: { id: "1234567" }) { deletedUser { id } } }

Response example

{ "data": { "userManagementDeleteUser": { "deletedUser": { "id": "1234567" } } } }

Add users to groups

• Method: POST
• URL: https://api.newrelic.com/graphql
• Watch out for: Groups control role and account access. A user with no group membership has no account access even if they exist in the system.

Request example

mutation { userManagementAddUsersToGroups(addUsersToGroupsOptions: { groupIds: ["GROUP_ID"], userIds: ["1234567"] }) { groups { id displayName users { totalCount } } } }

Response example

{ "data": { "userManagementAddUsersToGroups": { "groups": [{ "id": "GROUP_ID", "displayName": "Admins", "users": { "totalCount": 5 } }] } } }

Remove users from groups

• Method: POST
• URL: https://api.newrelic.com/graphql
• Watch out for: Removing a user from all groups revokes all account access but does not delete the user.

Request example

mutation { userManagementRemoveUsersFromGroups(removeUsersFromGroupsOptions: { groupIds: ["GROUP_ID"], userIds: ["1234567"] }) { groups { id displayName } } }

Response example

{ "data": { "userManagementRemoveUsersFromGroups": { "groups": [{ "id": "GROUP_ID", "displayName": "Admins" }] } } }

SCIM: Create user

• Method: POST
• URL: https://scim-provisioning.service.newrelic.com/scim/v2/Users
• Watch out for: SCIM token is scoped to a single authentication domain. Requires Pro/Enterprise plan with SSO configured. userType is not settable via standard SCIM; use NerdGraph to change user type after provisioning.

Request example

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "jane@example.com", "name": { "givenName": "Jane", "familyName": "Doe" }, "emails": [{ "value": "jane@example.com", "primary": true }], "active": true }

Response example

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "SCIM_USER_ID", "userName": "jane@example.com", "name": { "givenName": "Jane", "familyName": "Doe" }, "active": true }

SCIM: Deprovision user (deactivate)

• Method: PATCH
• URL: https://scim-provisioning.service.newrelic.com/scim/v2/Users/{id}
• Watch out for: Setting active: false deactivates the user and removes account access but does not delete the user record. A full DELETE request is required to permanently remove the user.

Request example

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "Replace", "path": "active", "value": false }] }

Response example

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "SCIM_USER_ID", "active": false }

• Rate limits: New Relic does not publish explicit numeric rate limits for NerdGraph in official documentation. SCIM API rate limits are also not publicly documented. Practical limits are enforced server-side; excessive requests may receive HTTP 429 responses.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: No official rate limit figures published. Implement exponential backoff on HTTP 429 responses. NerdGraph returns errors in the GraphQL errors array rather than HTTP error codes for most failures.
• Pagination method: cursor
• Default page size: 500
• Max page size: 500
• Pagination pointer: cursor

• Webhooks available: No
• Webhook notes: New Relic does not offer native webhooks for user-management events (user created, deleted, role changed). Webhooks in New Relic are limited to alerting/notification channels.
• Alternative event strategy: Poll NerdGraph customerAdministration { users } query on a schedule to detect changes. For real-time provisioning, use SCIM with an IdP (Okta, Azure AD, OneLogin) which pushes changes to New Relic automatically.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Pro or Enterprise

• Endpoint: https://scim-provisioning.service.newrelic.com/scim/v2

• Supported operations: GET /Users (list users), GET /Users/{id} (get user), POST /Users (create user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user), DELETE /Users/{id} (delete user), GET /Groups (list groups), GET /Groups/{id} (get group), POST /Groups (create group), PUT /Groups/{id} (replace group), PATCH /Groups/{id} (update group members), DELETE /Groups/{id} (delete group)

Limitations:

• Requires SAML SSO to be configured on the authentication domain before SCIM can be enabled.
• SCIM token is per-authentication-domain; organizations with multiple domains need separate tokens.
• User type (Basic/Core/Full Platform) cannot be set via standard SCIM attributes; must be managed via NerdGraph after provisioning.
• Once SCIM is enabled, users and groups in that domain must be managed exclusively via SCIM; manual UI management is disabled.
• Supported IdPs with native integrations: Okta, Azure AD (Entra ID), OneLogin. Other IdPs can use generic SCIM 2.0.
• Google Workspace does not have a native New Relic SCIM integration.

Three high-value automation scenarios emerge from the API surface. First, onboarding a Full Platform user via NerdGraph is a two-mutation sequence: userManagementCreateUser (returns a user ID) followed by userManagementAddUsersToGroups. Skipping the second mutation leaves the user authenticated but with zero account visibility - a silent failure that is easy to miss in automated pipelines.

Second, deprovisioning on SCIM-managed domains must go through the SCIM DELETE endpoint or the IdP, not NerdGraph. Deleting via NerdGraph on a SCIM-managed domain can cause sync conflicts; the IdP may re-provision the user on the next sync cycle.

Third, bulk user-type downgrade (e.g., Full Platform → Basic for inactive users) requires paginating the customerAdministration { users } query using nextCursor (max 500 per page), filtering client-side on lastActive and userType, then issuing userManagementUpdateUser mutations per user. Note that SCIM does not support the userType attribute - type changes must always go through NerdGraph, even on SCIM-managed domains.

Onboard a new full-platform user and assign to a group via NerdGraph

1. Query authentication domain ID: customerAdministration { authenticationDomains { authenticationDomains { id name } } }
2. Query target group ID: customerAdministration { groups(authenticationDomainId: "DOMAIN_ID") { groups { id displayName } } }
3. Run userManagementCreateUser mutation with name, email, authenticationDomainId, and userType: FULL_PLATFORM_USER_TIER.
4. Capture the returned createdUser.id.
5. Run userManagementAddUsersToGroups mutation with the group ID and new user ID to grant account access.

Watch out for: Skipping step 5 leaves the user with no account access. The user will be able to log in but will see no accounts or data.

Deprovision a user when they leave the organization

1. Look up the user ID by email: customerAdministration { users(authenticationDomainId: "DOMAIN_ID") { items { id email } } }
2. Run userManagementRemoveUsersFromGroups to remove from all groups (revokes access immediately).
3. Run userManagementDeleteUser mutation with the user ID to permanently delete the user record.
4. If the domain uses SCIM, perform DELETE /Users/{scim_id} instead - NerdGraph deletion may conflict with SCIM-managed domains.

Watch out for: On SCIM-managed authentication domains, deleting via NerdGraph may be overridden or cause sync conflicts. Use the SCIM DELETE endpoint or deprovision via the IdP for SCIM-managed domains.

Bulk downgrade inactive users from Full Platform to Basic via NerdGraph

1. Query all users with lastActive timestamp: customerAdministration { users(authenticationDomainId: "DOMAIN_ID") { items { id email lastActive userType { displayName } } } } - paginate with nextCursor until exhausted.
2. Filter client-side for users with userType = FULL_PLATFORM_USER_TIER and lastActive older than your threshold (e.g., 90 days).
3. For each inactive user, run userManagementUpdateUser mutation with userType: BASIC_USER_TIER.
4. Log all changes for audit purposes before executing.

Watch out for: Basic users lose access to full-platform features immediately. Confirm with stakeholders before bulk downgrading. On SCIM-managed domains, user type must still be managed via NerdGraph (not SCIM) as SCIM does not support the userType attribute.

NerdGraph returns errors as HTTP 200 responses with an errors array in the JSON body. Pipelines that check only HTTP status codes will silently swallow failures - including failed user creates, duplicate email conflicts, and permission errors. Every NerdGraph response must be inspected at the GraphQL layer, not the transport layer.

User API Keys inherit the permissions of the user who created them and are invalidated immediately if that user is deleted. Any automation key tied to a named employee account is a latent operational risk; keys should be tied to a dedicated service account user.

Rate limits for both NerdGraph and the SCIM API are not publicly documented. HTTP 429 responses are enforced server-side without published thresholds and without Retry-After headers. Implement exponential backoff unconditionally - do not assume a fixed safe request rate.