--- title: NerdGraph tutorial: Secrets management service source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-api-secret-management-service --- When you're working with New Relic, you might need to store sensitive information like API keys and application credentials. In New Relic, these are called secrets. The Secrets management service provides a secure way to store and retrieve these secrets in a centralized location through our [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/). > #### ⚠️ IMPORTANT > > You can store secrets only in string format. The key features of the Secrets management service are: - **Unique keys for secrets**: You can prevent accidental exposure of secrets by assigning a unique key to each one when storing. Use the key to retrieve and manage the secrets. - **Secrets stored at [account or organization level](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/new-relic-account-structure/)**: To access and use a secret across multiple accounts, you can store it at the organization level. If a secret is specific to a single account, you can store it at the account level. - **Versions of secrets**: You can update a secret without losing the previous version. The Secrets management service tracks all versions of a secret. - **Controlled deletion and recovery of secrets**: The service allows recoverable deletion of secrets. Users without the Purge permission can soft-delete secrets. Permanent deletion is restricted to users with the Purge permission. - **Standard secrets with role-based access**: Standard secrets are accessible to all users with permissions in the account or organization. Admins control access by assigning custom roles with permission levels ranging from **View** to **Purge**. - **Sharable secrets with fine-grained access**: Sharable secrets are private by default to the creator, who can grant specific permissions (read, update, delete) to individual users, groups, or system identities. Organization admins retain full access to all sharable secrets for oversight and management. ## Secrets management services billing [#secrets-management-services-billing] The Secrets management service is an Advanced Compute Product feature offered as an [add-on](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-pricing-billing/add-on-billing) or as a part of the Compute pricing model. Advanced [CCUs](https://docs.newrelic.com/docs/licenses/license-information/product-definitions/new-relic-one-pricing-definitions/#compute-capacity-unit) are consumed when NerdGraph queries are executed to store, retrieve, or manage secrets. ## Standard secrets access control [#security-and-access-control] Users with [standard roles](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#standard-roles) can access the Secrets management service specific to the accounts they have access to, with the following permissions. - **Read Only**: Users can only retrieve secrets. They can't create, update, or delete secrets. - **Standard User**: Users can create, update, retrieve, and soft-delete secrets. - **All Product Admin**: Users have full access to the Secrets management service. They can create, update, retrieve, soft-delete, permanently delete, and fetch the list of secrets. - **Billing User**: Users can only fetch the list of secrets. To manage secrets at the account level with a non-standard role, ask your admin to [create a custom role](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/account-user-mgmt-tutorial/#roles) with the necessary permissions, and assign them to your user group. For managing secrets at the organization level, ask your admin to create an [org-scoped custom role via the NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-manage-groups/#create-role), add the required permissions, and assign it to the user group. [Organization Manager](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#admin-settings) have default permissions at the organization level, but to allow them to manage secrets, ask your admin to assign them a custom role specific to the Secrets management service. > #### ⚠️ IMPORTANT > > Setup and configure the users, roles, permissions, and access to the Secrets management service at the account and organization level, in accordance with your organization policies and requirements. ## Sharable secrets with fine-grained access [#sharable-secrets] While standard secrets are accessible to all users with permissions in an account or organization, enterprises with multiple teams often need to restrict secrets to specific individuals. Sharable secrets address this need. > #### ⚠️ IMPORTANT > > To work with sharable secrets, users must first have the base permissions described in [Standard secrets access control](#security-and-access-control). The fine-grained access permissions described below are **in addition to** those base requirements. When you create a sharable secret, you automatically become its owner with full control. You can grant access to users, groups, or system identities by assigning individual permissions or by using roles that bundle multiple permissions together. **Individual permissions (granted on top of base access):** - **Read**: Retrieve the secret value - **Update**: Change the secret value - **Delete**: Remove the secret **Predefined roles (granted on top of base access):** - **Secret Owner**: Full control (read, update, delete, grant/revoke) - **Secret Reader**: Read-only access You can also [create custom roles]((/docs/accounts/accounts-billing/new-relic-one-user-management/account-user-mgmt-tutorial/#roles)) that combine specific permissions based on your needs. Organization admins retain full access to all sharable secrets for oversight. When you need a synthetic monitor, workflow, or other automated process to access your secret, you grant access to its system identity. A system identity is a unique identifier assigned to each automated process in New Relic. When you link a secret to a monitor or workflow through the New Relic UI, the system identity for that automated process is used to control access at runtime. > #### ⚠️ IMPORTANT > > Standard secrets cannot be converted into sharable secrets. To migrate an existing standard secret, create a new sharable secret with the same value, grant appropriate access, update your applications, and delete the old secret. ## Pre-requisites [#prerequisites] To use the Secrets management service, you need: - The [Advanced Compute](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-pricing-billing/add-on-billing) pricing plan - A [New Relic account](https://newrelic.com/signup) - Your API user key for [queries and mutations]((https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/#terminology)) - Appropriate permissions to create and manage secrets. Refer to [Standard secrets access control](#security-and-access-control) and [Sharable secrets with fine-grained access](#sharable-secrets) for details on required roles and permissions. User type and assigned roles can affect your NerdGraph permissions. For more details, refer [Factors affecting access](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/factors-affecting-access-features-data/#user-permissions). ## Use the Secrets management service [#use-secrets-management-service] From the [NerdGraph Explorer](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/nerdgraph-explorer/), use [mutations and queries](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/factors-affecting-access-features-data/#user-permissions) to interact with the Secrets management service. Here are the common attributes you will use in the mutations and queries: | **Attribute name** | **Data type** | **Description** | | ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `description` | String | A brief description of the secret. | | `key` | String | A unique identifier for the secret within a namespace. The same key can exist across different namespaces. | | `namespace` | String | Serves as a logical grouping of secrets, organizing and categorizing them to enhance management and prevent conflicts. It pairs with the key to create a unique address for the secret. This attribute is beneficial in environments with multiple teams or projects using New Relic. | | `scope` | - `type`: Enum - `id`: string | The scope of storing the secrets in terms of its accessibility. The defining attributes are: - `type`: To use the secret across multiple accounts, select `Organization`. If the secret is specific to a single account, select `Account`. To store a secret at the organization level, you must have the [org-scoped custom role](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-manage-groups/#create-role) with the required permissions. Refer to the [Access control](#security-and-access-control) section for more details. - `id`: Corresponding account or organization ID. | | `tags` | Array | Functions as key-value pairs that add metadata to your entities, including applications, services, and hosts. Using tags you can enhance the ability to organize, filter, and manage secrets. | | `value` | String | The actual secret. | | `purge` | Boolean | Deletes all versions of the secret. - `true`: Deletes the secret permanently. - `false`: You can recover the deleted secret with all its versions. Only All Product Admins or a user having a custom role with `purge` permission can delete secrets permanently. For more details, refer to the [Access control](#security-and-access-control) section. | | `version` | String | As you can store multiple versions of a secret, it represents the version number of the secret. | | `cursor` (Optional) | String | When retrieving a list of secrets, if the response contains the `nextCursor` attribute, it indicates that there are more secrets available beyond the current page of results. To access the next page of results, use the `nextCursor` value in the `cursor` attribute and run the query again. | > #### ⚠️ IMPORTANT > > Copy your actual secret only into the `value` attribute. Ensure it is not declared in any other attributes, such as `description`, `key`, or `namespace`. ### Operations[#operations] The operations you can perform with the Secrets management service are organized into two categories: > #### 💡 TIP > > **Choosing between standard and sharable secrets:** > > - Use **standard secrets** (`secretsManagementCreateSecret`) when you want to share a secret with all users who have access to the account or organization. > - Use **sharable secrets** (`secretsManagementCreateShareableSecret`) when you need to control exactly who can access a secret by granting permissions to specific users, groups, or system identities. **Store a secret** Use the `secretsManagementCreateSecret` mutation with the following parameters to store a standard secret that will be accessible to all users with permissions in the specified account or organization. | **Attribute name** | **Data type** | **Description** | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `description` (Optional) | String | Give a description for the secret. | | `key` (Required) | String | Assign a unique key for the secret. | | `namespace` (Optional) | String | Assign a name if you want to store the secret in a specific namespace. | | `scope` (Required) | `type`: Enum `id`: string | - `type`: Based on your [role](#security-and-access-control) and requirements, select `Account` or `Organization`. - `id`: Enter the corresponding account or organization ID. | | `tags` (Optional) | Array | Assign a key and value pair. | | `value` (Required) | String | Enter the actual secret. | #### Sample query: ```graphql mutation { secretsManagementCreateSecret( description: "ZXY" key: "Test2" scope: { id: 1, type: ACCOUNT } value: "1990@123" namespace: "Namespace1" ) } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ------------------------------------------------------------------------------------- | | `description` | The description of the secret, if provided. | | `key` | The assigned key. | | `latestVersion` | The version of the secret. If you have created a new secret, the version will be `0`. | | `metadata` | Associated metadata with the secret, if any. | | `namespace` | The namespace of the secret, if provided. | | `scope` | The account or organization ID associated with the secret. | | `tags` | The key and value pair associated with the secret, if any. | #### Sample response: ```json { "data": { "secretsManagementCreateSecret": { "description": "ZXY", "key": "Test2", "latestVersion": 0, "scope": { "id": "1", "type": "ACCOUNT" } } } ``` **Store a sharable secret** Use the `secretsManagementCreateShareableSecret` mutation to create a private secret with fine-grained access control. When you create a sharable secret, you automatically become the owner with full control over who can access it. | **Attribute name** | **Data type** | **Description** | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `description` (Optional) | String | Give a description for the secret. | | `key` (Required) | String | Assign a unique key for the secret. | | `namespace` (Optional) | String | Assign a name if you want to store the secret in a specific namespace. | | `scope` (Required) | `type`: Enum `id`: string | - `type`: Based on your [role](#security-and-access-control) and requirements, select `Account` or `Organization`. - `id`: Enter the corresponding account or organization ID. | | `tags` (Optional) | Array | Assign a key and value pair. | | `value` (Required) | String | Enter the actual secret. | #### Sample query: ```graphql mutation { secretsManagementCreateShareableSecret( scope: { type: ACCOUNT, id: 1 } key: "prod-api-key" value: "sk_live_abc123xyz" namespace: "production" description: "Private API key for production" tags: [{ key: "environment", value: "production" }] ) { scope { type id } key namespace latestVersion description tags { key value } metadata { createdAt updatedAt } } } ``` ### Response | **Attribute name** | **Description** | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | The description of the secret, if provided. | | `key` | The assigned key. | | `latestVersion` | The version of the secret. If you've created a new secret, the version will be `0`. | | `metadata` | Associated metadata with the secret, including: - `createdAt`: Timestamp when the secret was created - `updatedAt`: Timestamp when the secret was last updated | | `namespace` | The namespace of the secret, if provided. | | `scope` | The account or organization ID associated with the secret. | | `tags` | The key and value pair associated with the secret, if any. | #### Sample response: ```json { "data": { "secretsManagementCreateShareableSecret": { "scope": { "type": "ACCOUNT", "id": "1" }, "key": "prod-api-key", "namespace": "production", "latestVersion": 0, "description": "Private API key for production", "tags": [ { "key": "environment", "value": "production" } ], "metadata": { "createdAt": "2025-10-30T12:34:56.789Z", "updatedAt": "2025-10-30T12:34:56.789Z" } } } } ``` > #### 💡 TIP > > After creating a sharable secret, you become the owner automatically. To grant access to other users, groups, or system identities, use the `authorizationManagementGrantAccess` mutation. For more details, see the [Grant access to a sharable secret](#grant-access-sharable-secret) section. **Retrieve a secret** Use the `{customerAdministration {secret}}` query to retrieve secrets along with their details. You can retrieve secrets that are scoped only for your current account or organization. | **Attribute name** | **Data type** | **Description** | | ---------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` (Required) | String | Key of the secret that you want to retrieve. | | `namespace` (Optional) | String | The namespace of the secret, if available. | | `scope` (Required) | `type`: Enum `id`: string | - `type`: Select `account` or `organization` in which level the secret is stored. - `id`: Enter the corresponding account or organization ID. | | `unlock` (Optional) | String | The default value `false` returns the metadata of the secret without unlocking it. If you want to unlock the secret and retrieve its actual value, set it to `true`. | | `version` (Optional) | Integer | Enter a specific version of the secret that you want to retrieve. If you do not provide a version, the latest version will be retrieved. | #### Sample query: ```graphql { customerAdministration { secret(key: "Test2", scope: { id: 1, type: ACCOUNT }, unlock: true) } } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `description` | The description of the secret. | | `isSharable` | Indicates whether the secret is a [sharable secret](#sharable-secrets) with fine-grained access control. If `true`, the secret uses fine-grained permissions and is private to the creator by default. If `false`, it's a standard secret accessible to all users with permissions in the account or organization. | | `key` | The key of the secret. | | `metadata` | Associated metadata with the secret, if any. | | `namespace` | The namespace of the secret, if provided. | | `retrievedValue` | - `value`: The actual secret value, if `unlock` is set to `true`. - `version`: The version of the secret. | | `scope` | The account or organization ID associated with the secret. | | `tags` | The key and value pair associated with the secret, if any. | #### Sample response: ```json { "data": { "customerAdministration": { "secret": { "description": "ZXY", "isSharable": false, "key": "Test2", "namespace": null, "retrievedValue": { "value": "1995@123", "version": 1 }, "scope": { "id": "1", "type": "ACCOUNT" } } } } } ``` **Update a secret** Use the `secretsManagementUpdateSecret` mutation to update the value of existing secrets. > #### 💡 TIP > > Each update operation creates a new version of the secret. The highest version is always the latest version of the secret. To retrieve older versions of the secret, you can use the `{customerAdministration {secretVersions}}` query. For more details, refer to the [Retrieve all version information of a secret](#retrieve-secret-versions) section. #### Input Parameters | **Attribute name** | **Data type** | **Description** | | ------------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `description` (Optional) | String | Add a description if you want to update the existing one. | | `key` (Required) | String | Enter the key of the secret for which you want to update the value. | | `namespace` (Optional) | String | Namespace of the secret, if available. | | `scope` (Required) | `type`: Enum `id`: string | - `type`: Select `Account` or `Organization` in which level the secret is stored. - `id`: Enter the corresponding account or organization ID. | | `value` (Required) | String | The updated value for the secret. | #### Sample query: ```graphql mutation { secretsManagementUpdateSecret( key: "Test2" scope: { id: 1, type: ACCOUNT } value: "1995@123" ) } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ---------------------------------------------------------- | | `description` | Updated description of the secret, if provided. | | `key` | The key of the secret. | | `latestVersion` | The latest version number of the secret after the update. | | `metadata` | Associated metadata with the secret, if any. | | `namespace` | The namespace of the secret, if any. | | `scope` | The account or organization ID associated with the secret. | | `tags` | The key and value pair associated with the secret, if any. | #### Sample response: ```json { "data": { "secretsManagementUpdateSecret": { "description": "ZXY", "key": "Test2", "latestVersion": 1, "scope": { "id": "1", "type": "ACCOUNT" } } } } ``` **Retrieve all version information of a secret** Use the `{customerAdministration {secretVersions}}` query to retrieve up to 10 recent versions of a secret along with their details. You can retrieve secrets that are scoped only to your current account or organization. | **Attribute name** | **Data type** | **Description** | | ------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fetchDeleted` (Optional) | String | To get only the non-deleted versions of the secret, set it to `false`. To get versions of the secret, including the soft-deleted ones, set it to `true`. | | `key` (Required) | String | Key of the secret that you want to retrieve. | | `namespace` (Optional) | String | The namespace of the secret, if available. | | `scope` (Required) | `type`: Enum `id`: string | - `type`: Select `account` or `organization` in which level the secret is stored. - `id`: Enter the corresponding account or organization ID. | #### Sample query: ```graphql { customerAdministration { secretVersions( fetchDeleted: true key: "Test2" scope: { id: 1, type: ACCOUNT } ) } } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `key` | The key of the secret. | | `latestVersion` | The latest version number of the secret. | | `namespace` | The namespace of the secret, if provided. | | `scope` | The account or organization ID associated with the secret. | | `secretVersions` | An array of objects containing the details of each version of the secret, including: - `createdAt`: Timestamps indicating when each version was created. - `isDeleted`: Indicates whether the secret version is deleted or not. - `version`: The version number of the secret. | #### Sample response: ```json { "data": { "customerAdministration": { "secretVersions": { "key": "Test2", "latestVersion": 1, "namespace": null, "scope": { "id": "1", "type": "ACCOUNT" }, "secretVersions": [ { "createdAt": "2025-05-26T07:52:23.920250Z", "isDeleted": false, "version": 1 }, { "createdAt": "2025-05-26T07:45:19.395796Z", "isDeleted": false, "version": 0 } ] } } } } ``` **Delete a secret** Use the `secretsManagementDeleteSecret` mutation to delete all versions of a secret. Only All Product Admins or a user having a custom role with `purge` permission can choose to delete secrets permanently. Other users can't delete secrets permanently. If you have not deleted the secret permanently, you can [recover it](#recover-secrets) using the `secretsManagementRecoverSecret` mutation. #### Input attributes | **Attribute name** | **Data type** | **Description** | | ---------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `key` (Required) | String | The key for the secret that you want to delete. | | `namespace` (Optional) | String | Namespace of the secret, if available. | | `purge` (Required) | Boolean | To delete the secret permanently,set the value to `true` . For soft deletion, set the value to `false`. | | `scope` (Required) | `type`: Enum `id`: string | - `type`: Select the level at which your secret is stored. - `id`: Enter the corresponding account or organization ID. | #### Sample query: ```graphql mutation { secretsManagementDeleteSecret( key: "Test1" scope: { id: 1, type: ACCOUNT } purge: false ) } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ------------------------------------------------------------------ | | `key` | The key of the deleted secret. | | `namespace` | The namespace of the deleted secret, if available. | | `scope` | The account or organization ID associated with the deleted secret. | #### Sample response: ```json { "data": { "secretsManagementDeleteSecret": { "key": "Test1", "namespace": null, "scope": { "id": "1", "type": "ACCOUNT" } } } } ``` **Recover a secret** Use `secretsManagementRecoverSecret` mutation to recover secrets that you have deleted using the `secretsManagementDeleteSecret` mutation before with the `purge` attribute set to `false`. If a secret is permanently deleted, you can't recover it. #### Input attributes | **Attribute name** | **Data type** | **Description** | | ---------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` (Required) | String | The key for the secret that you want to recover. | | `namespace` (Optional) | String | The namespace of the deleted secret, if available. | | `scope` (Required) | `type`: Enum `id`: string | - `type`: Select `Account` or `Organization` in which level the secret was stored. - `id`: Enter the corresponding ID of the account or organization. | #### Sample query: ```graphql mutation { secretsManagementRecoverSecret(key: "Test1", scope: { id: 1, type: ACCOUNT }) } ``` ### Response | **Attribute name** | **Description** | | ------------------ | -------------------------------------------------------------------- | | `key` | The key of the recovered secret. | | `latestVersion` | The latest version of the recovered secret. | | `namespace` | The namespace of the recovered secret, if available. | | `scope` | The account or organization ID associated with the recovered secret. | #### Sample response: ```json { "data": { "secretsManagementRecoverSecret": { "key": "Test1", "latestVersion": 1, "namespace": null, "scope": { "id": "1", "type": "ACCOUNT" } } } } ``` **Delete a specific version of a secret** Use the `secretsManagementDeleteSecretVersion` mutation to delete a specific version of a secret. Only All Product Admins or a user having a custom role with `purge` permission can choose to delete it permanently. Other users can't delete the secret version permanently. If you have not deleted the secret version permanently, you can [recover it](#recover-secrets-versions) using the `secretsManagementDeleteSecretVersion` mutation. #### Input attributes | **Attribute name** | **Data type** | **Description** | | ---------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` (Required) | String | The key of the secret for which you want to delete one of the versions. | | `namespace` (Optional) | String | Namespace of the secret, if available. | | `purge` (Required) | Boolean | To delete the secret version permanently, set the value to `true`. For soft deletion, set the value to `false`. | | `scope` (Required) | `type`: Enum `id`: string | - `type`: Select the level at which your secret is stored. - `id`: Enter the corresponding ID of the account or organization. | | `version` (Optional) | String | The specific version of the secret that you want to delete. If you do not provide a version, the latest version will be deleted, and the previous version will become the latest version. | #### Sample query: ```graphql mutation { secretsManagementDeleteSecretVersion( key: "Test2" purge: false scope: { id: 1, type: ACCOUNT } version: 0 ) } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ----------------------------------------------------------------------------------- | | `key` | The key of the secret. | | `latestVersion` | The latest version of the secret available after deletion of the specified version. | | `namespace` | The namespace of the secret, if available. | | `scope` | The account or organization ID associated with the secret. | #### Sample response: ```json { "data": { "secretsManagementDeleteSecretVersion": { "key": "Test2", "latestVersion": 1, "scope": { "id": "1" } } } } ``` **Recover a secret version** Use `secretsManagementRecoverSecretVersion` mutation to recover a specific version of the secret that you have soft-deleted using the `secretsManagementDeleteSecretVersion` mutation. If a version is permanently deleted, you can't recover it. #### Input attributes | **Attribute name** | **Data type** | **Description** | | ---------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` (Required) | String | The key of the secret for which you want to recover one of the versions. | | `namespace` (Optional) | String | The namespace of the secret, if available. | | `scope` (Required) | `type`: Enum `id`: string | - `type`: Select `Account` or `Organization` in which level the secret belongs. - `id`: Enter the corresponding ID of the account or organization. | | `version` (Optional) | String | Enter the version number of the secret that you want to recover. If you do not provide a version, it recovers the highest version of the secret that was soft-deleted. | #### Sample query: ```graphql mutation { secretsManagementRecoverSecretVersion( key: "Test2" scope: { id: 1, type: ACCOUNT } version: 0 ) } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ---------------------------------------------------------- | | `key` | The key of the secret. | | `latestVersion` | The latest version of the secret after recovery. | | `namespace` | The namespace of the secret, if available. | | `scope` | The account or organization ID associated with the secret. | #### Sample response: ```json { "data": { "secretsManagementRecoverSecretVersion": { "key": "Test2", "latestVersion": 1, "namespace": null, "scope": { "id": "1", "type": "ACCOUNT" } } } } ``` **Retrieve the list of secrets** Use the `{customerAdministration {secrets}}` query to retrieve a list of secrets available in the account or organization. You can retrieve secrets that are scoped only for your current account or organization. > #### 💡 TIP > > The list includes all secrets in the scope, including sharable secrets you may not have permission to access. Access permissions are enforced when you retrieve the secret value using the [Retrieve a secret](#retrieve-secret) operation. | **Attribute name** | **Data type** | **Description** | | ------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cursor` (Optional) | String | Use the `cursor` to navigate through secret lists. To get the first page of the secret list this parameter is not required. If you want to access the next page, use the `NextCursor` value from the previous response. | | `filter` (Required) | - `deleted` (Optional): Boolean - `namespace` (Optional): String - `scope` (Required) - `type`: Enum - `id`: string | Add the following filter to apply the search criteria: - `deleted`: To get all the secrets including the soft-deleted ones, set it to `true`. To get only the non-deleted secrets, set it to `false`. - `namespace`: To filter secrets by namespace, provide the namespace name. - `scope`: To filter secrets by scope, provide the level (`Account` or `Organization`) and the corresponding ID. | | `sort` (Optional) | - `direction` (Required): Boolean - `key` (Required): Boolean | To sort the list of secrets, provide the following attributes: - `direction`: Select `ASC` for ascending order or `DESC` for descending order. - `key`: The available option is `CREATED_AT`. This sorts the secrets based on their creation time. | #### Sample query: ```graphql { customerAdministration { secrets( filter: { deleted: { eq: false } scope: { eq: { id: 1, type: ACCOUNT } } } cursor: "" sort: { direction: DESC, key: CREATED_AT } ) } } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `nextCursor` | The cursor value to access the next page of the secret list. If there are no more pages, this value will be `null`. | | `scope` | The account or organization ID associated with the secret. | | `secrets` | The details of the listed secrets, including: - `description`: The description of the secret, if available. - `isDeleted`: Indicates whether the secret is in a soft-delete state or not. - `isSharable`: Indicates whether the secret is a [sharable secret](#sharable-secrets) with fine-grained access control. - `key`: The key of the secret. - `latestVersion`: The latest version number of the secret. - `metadata`: Metadata associated with the secret, if any. - `createdAt`: Timestamps indicating when the secret was created. - `updatedAt`: Timestamps indicating when the secret was last updated. - `namespace`: The namespace of the secret, if available. - `tags`: The key and value pair associated with the secret, if any. | | `totalCount` | The total number of secrets available in the account or organization, regardless of pagination. | #### Sample response: ```json { "data": { "customerAdministration": { "secrets": { "nextCursor": "AAAADJ_Fqig86wFIH6c3ehxxpoFy0vdW2eA4pTkQFYDztd_UIeL91kCElQaCG0iORpmDdDT6KeZAVkByh4ogENST8yjxeZ5tI6vPYnyMW5rhtGwXlgt9zQRGYj1HcdpUHdfUcTC-CSsdQDLexy52XA==", "scope": { "id": "1", "type": "ACCOUNT" }, "secrets": [ { "description": "ZXY", "isDeleted": false, "isSharable": false, "key": "test2", "latestVersion": 1, "metadata": { "createdAt": "2025-05-26T07:45:19.395796Z", "updatedAt": "2025-05-26T08:08:49.130724Z" }, "namespace": null, "tags": null }, { "description": "XYZ", "isDeleted": false, "isSharable": false, "key": "test2", "latestVersion": 0, "metadata": { "createdAt": "2025-05-26T07:26:32.114987Z", "updatedAt": "2025-05-26T07:26:32.114987Z" }, "namespace": null, "tags": null }, { "description": "CBA", "isDeleted": false, "isSharable": false, "key": "test1", "latestVersion": 1, "metadata": { "createdAt": "2025-05-26T07:15:08.987252Z", "updatedAt": "2025-05-26T08:05:17.051658Z" }, "namespace": null, "tags": null } ], "totalCount": 3 } } } } ``` **Grant access to a sharable secret** After creating a sharable secret, you can grant specific permissions to users, groups, system identities, or system identity groups. Use the `authorizationManagementGrantAccess` mutation to share your secret with authorized entities. > #### ⚠️ IMPORTANT > > The secret owner (creator), organization admins, or users with the `secret.create.grants` capability can grant access to a sharable secret. #### Input attributes | **Attribute name** | **Data type** | **Description** | | ------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `grantAccessOptions` (Required) | Object | Contains the grant configuration with two main components: - `entityAccessGrants`: Defines the secret and the role to grant - `grantee`: Specifies who receives access | | `entityAccessGrants.entity.id` (Required) | String | The unique ID of the secret. The format is `namespace::partition::entry_key_secret`. For example, if you created a secret with key `prod-api-key` in account `12345` with namespace `production`, the entity ID is: `production::account-12345::prod-api-key`. If no namespace was provided, use an empty string: `::account-12345::prod-api-key`. | | `entityAccessGrants.entity.type` (Required) | String | The entity type. For secrets, this is always `secret`. | | `entityAccessGrants.roleId` (Required) | String | The unique ID of the role to grant. To find available role IDs, use the NerdGraph API explorer to query roles with scope `secret`. Common roles include Secret Owner (full control) and Secret Reader (read-only access). | | `grantee.id` (Required) | String | The unique ID of the user, group, system identity, or system identity group receiving access. | | `grantee.type` (Required) | Enum | The type of grantee. Valid values: - `USER`: Individual user - `GROUP`: User group - `SYSTEM_IDENTITY`: System identity (for automated processes) - `SYSTEM_IDENTITY_GROUP`: System identity group | #### Sample query: ```graphql mutation { authorizationManagementGrantAccess( grantAccessOptions: { entityAccessGrants: { entity: { id: "production::account-1::prod-api-key", type: "secret" }, roleId: "role-id-for-secret-reader" }, grantee: { id: "system-identity-id-abc123", type: SYSTEM_IDENTITY } } ) { roles { id roleId } } } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `roles` | An array of role assignments created by the grant operation, including: - `id`: The unique identifier of the grant - `roleId`: The role ID that was granted | #### Sample response: ```json { "data": { "authorizationManagementGrantAccess": { "roles": [ { "id": "grant-id-xyz789", "roleId": "role-id-for-secret-reader" } ] } } } ``` > #### 💡 TIP > > To revoke access to a sharable secret, use the `authorizationManagementRevokeAccess` mutation. **Revoke access to a sharable secret** Use the `authorizationManagementRevokeAccess` mutation to remove access from users, groups, system identities, or system identity groups that were previously granted access to your sharable secret. > #### ⚠️ IMPORTANT > > The secret owner (creator), organization admins, or users with the appropriate revoke permission can remove access to a sharable secret. #### Input attributes | **Attribute name** | **Data type** | **Description** | | ------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------- | | `grantAccessOptions` (Required) | Object | Contains the revoke configuration with the same structure as the grant operation. | | `entityAccessGrants.entity.id` (Required) | String | The unique ID of the secret in the format `namespace::partition::entry_key_secret`. | | `entityAccessGrants.entity.type` (Required) | String | The entity type. For secrets, this is always `secret`. | | `entityAccessGrants.roleId` (Required) | String | The unique ID of the role to revoke. | | `grantee.id` (Required) | String | The unique ID of the user, group, system identity, or system identity group from which to revoke access. | | `grantee.type` (Required) | Enum | The type of grantee. Valid values: `USER`, `GROUP`, `SYSTEM_IDENTITY`, `SYSTEM_IDENTITY_GROUP`. | #### Sample query: ```graphql mutation { authorizationManagementRevokeAccess( grantAccessOptions: { entityAccessGrants: { entity: { id: "production::account-12345::prod-api-key", type: "secret" } roleId: "role-id-for-secret-reader" } grantee: { id: "system-identity-id-abc123", type: SYSTEM_IDENTITY } } ) { roles { id roleId } } } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ---------------------------------------------------------- | | `roles` | An array of role information related to the revoked grant. | #### Sample response: ```json { "data": { "authorizationManagementRevokeAccess": { "roles": [ { "id": "grant-id-xyz789", "roleId": "role-id-for-secret-reader" } ] } } } ``` **List who has access to a sharable secret** Use the `customerAdministration/entityGrants` query to see which users, groups, system identities, or system identity groups have been granted access to your sharable secret. > #### 💡 TIP > > This query returns only explicit grants made directly on the secret. It does not show implied access or permissions inherited from parent scopes. #### Input attributes | **Attribute name** | **Data type** | **Description** | | ---------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `iamParent.id` (Required) | String | The ID of the account or organization where the secret is stored. | | `iamParent.scope` (Required) | Enum | The parent scope type. Valid values: `ACCOUNT`, `ORGANIZATION`. | | `entity.id` (Optional) | String | The unique ID of the secret in the format `namespace::partition::entry_key_secret`. When provided, only grants for this specific secret are returned. | | `entity.type` (Required) | String | The entity type. For secrets, this is always `secret`. | | `member.id` (Optional) | String | Filter grants by the ID of a specific user, group, system identity, or system identity group. | | `member.type` (Optional) | Enum | The type of member to filter by. Valid values: `USER`, `GROUP`, `SYSTEM_IDENTITY`, `SYSTEM_IDENTITY_GROUP`. | #### Sample query: ```graphql { customerAdministration { entityGrants( filter: { iamParent: { id: { eq: "12345" } scope: { eq: ACCOUNT } } entity: { id: { eq: "production::account-12345::prod-api-key" } type: { eq: "secret" } } } cursor: "" ) { items { targetEntity { id } member { memberId memberType } id role { name id } } nextCursor } } } ``` ### Response | **Attribute name** | **Description** | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `items` | An array of grant objects, each containing: - `targetEntity.id`: The entity ID of the secret - `member.memberId`: The ID of the user, group, system identity, or system identity group - `member.memberType`: The type of member (USER, GROUP, SYSTEM_IDENTITY, or SYSTEM_IDENTITY_GROUP) - `id`: The unique identifier of the grant (use this to revoke access) - `role.name`: The name of the role granted - `role.id`: The unique identifier of the role | | `nextCursor` | The cursor value for pagination. Use this value in the next query to retrieve additional results. | #### Sample response: ```json { "data": { "customerAdministration": { "entityGrants": { "items": [ { "targetEntity": { "id": "production::account-12345::prod-api-key" }, "member": { "memberId": "system-identity-id-abc123", "memberType": "SYSTEM_IDENTITY" }, "id": "grant-id-xyz789", "role": { "name": "Secret Reader", "id": "role-id-for-secret-reader" } } ], "nextCursor": null } } } } ``` ## Related topics [#related-topics] [Introduction to NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph) Get started with New Relic's GraphQL API [NerdGraph API explorer](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/nerdgraph-explorer) Use the NerdGraph API explorer to test queries and mutations [Manage user groups](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-manage-groups) Create and manage user groups with custom roles [Secrets management for infrastructure](https://docs.newrelic.com/docs/infrastructure/host-integrations/installation/secrets-management) Use secrets in infrastructure agent configuration