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.
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:
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.
Access control: Admins can define who can access the secrets by setting custom roles and permissions, and specifying the scope of permissions. The scope can range from View to Purge permissions.
Secrets management services billing
The Secrets management service is an Advanced Compute Product feature offered as an add-on or as a part of the Compute pricing model. Advanced CCUs are consumed when NerdGraph queries are executed to store, retrieve, or manage secrets.
Access control
Users with 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 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, add the required permissions, and assign it to the user group. Organization Manager 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.
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 with the required permissions. Refer to the 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 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
The operations you can perform with the Secrets management service are as follows:
Use the secretsManagementCreateSecret mutation with the following parameters to store a secret.
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 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:
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:
{
"data":{
"secretsManagementCreateSecret":{
"description":"ZXY",
"key":"Test2",
"latestVersion":0,
"scope":{
"id":"1",
"type":"ACCOUNT"
}
}
}
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.
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:
{
"data":{
"customerAdministration":{
"secret":{
"description":"ZXY",
"key":"Test2",
"namespace":null,
"retrievedValue":{
"value":"1995@123",
"version":1
},
"scope":{
"id":"1",
"type":"ACCOUNT"
}
}
}
}
Use the secretsManagementUpdateSecret mutation to update the value of existing secrets.
Conseil
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 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:
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:
{
"data":{
"secretsManagementUpdateSecret":{
"description":"ZXY",
"key":"Test2",
"latestVersion":1,
"scope":{
"id":"1",
"type":"ACCOUNT"
}
}
}
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:
{
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:
{
"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
}
]
}
}
}
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 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:
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:
{
"data":{
"secretsManagementDeleteSecret":{
"key":"Test1",
"namespace":null,
"scope":{
"id":"1",
"type":"ACCOUNT"
}
}
},
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.
The namespace of the recovered secret, if available.
scope
The account or organization ID associated with the recovered secret.
Sample response:
{
"data":{
"secretsManagementRecoverSecret":{
"key":"Test1",
"latestVersion":1,
"namespace":null,
"scope":{
"id":"1",
"type":"ACCOUNT"
}
}
}
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 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:
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:
{
"data":{
"secretsManagementDeleteSecretVersion":{
"key":"Test2",
"latestVersion":1,
"scope":{
"id":"1"
}
}
}
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:
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:
{
"data":{
"secretsManagementRecoverSecretVersion":{
"key":"Test2",
"latestVersion":1,
"namespace":null,
"scope":{
"id":"1",
"type":"ACCOUNT"
}
}
}
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.
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:
{
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.
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.