Use Synthetics secure credentials APIs

Owner or Admins

Access to this feature depends on your subscription level.

With the New Relic Synthetics REST API, you can make API calls to change or retrieve secure credentials data. This document explains the API requirements and contains API cURL command examples.

For general guidelines for setting secure credentials and setting them in the UI, see Secure credentials.

Requirements and rules

For general rules about this feature, see the secure credentials requirements.

API requirements and rules include:

  • To use the Synthetics REST API, you must activate your API access and generate your Admin User's API key from your account settings. Then you can make standard API calls via the command line.
  • You must use your Admin User's API key to make Synthetics REST API calls. The account's REST API key will not work.
  • An account's rate of requests is limited to three requests per second. Requests that exceed this threshold will return a 429 response code.

  • A key's value cannot be accessed via the API; an unauthorized user would not have access to the secure key values.

API examples

Add a secure credential

To send a secure credential to your Synthetics account, send a POST request to https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials with a JSON payload that describes the secure credential. Here's an example:

{
  "key": string [required, 1-64 characters uppercase],
  "value": string [required, 1-3,000 characters],
  "description": string [optional]
}

Here's an example of doing this with a cURL command:

curl -v 
     -X POST -H 'X-Api-Key:{Admin_User_Key}' \
     -H 'Content-Type: application/json' https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials \
     -d  '{ "key": "myKey", "value": "my value", "description": "Description of myKey" }'

A successful request will return a 201 Created response, with the URI of the newly-created secure credential specified in the location header. Possible error codes include:

  • 303 See Other: The specified key already exists. The returned location header will contain the URI to the key.
  • 400 Bad Request: Key too long or missing, value too long or missing, non-parsable JSON payload.
Get all secure credentials

To view a list of all the secure credentials in your New Relic Synthetics account, send a GET request to https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials. For example:

curl -v 
     -H 'X-Api-Key:{Admin_User_Key}' https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials

A successful request will return a 200 OK response. The data returned will be a JSON object in the following format:

{
  "secureCredentials": [
    {
      "key": "myKey1",
      "description": "Description of myKey1",
      "createdAt": "2016-09-26T23:12:46.981+0000",
      "lastUpdated": "2016-09-26T23:12:46.981+0000"
    }, {
      "key": "myKey2",
      "description": "Description of myKey2",
      "createdAt": "2016-09-26T23:12:46.981+0000",
      "lastUpdated": "2016-09-26T23:12:46.981+0000"
    }
  ],
  "count": 2
}
Get a specific secure credential

To view a single secure credential, send a GET request to https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials/{key}. Replace the {key} and {Admin_User_Key} in the following example with the specific key.

curl -v \
     -H 'X-Api-Key:{Admin_User_Key}' https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials/{key}

A successful request will return a 200 OK response. The data returned will be a JSON object in the following format:​

{
  "key": string,
  "description": string,
  "createdAt": date,​
  "lastUpdated": date
}

An invalid key will return 404 Not Found: The specified key doesn't exist.

Update an existing secure credential

To update an existing credential in Synthetics, send a PUT request to https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials/{key}. Replace the {key} in the following example with the specific key:

curl -v
     -X PUT -H 'X-Api-Key:{Admin_User_Key}' \
     -H 'Content-Type: application/json' https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials/{key} \
     -d  '{ "key": "myKey", "value": "my value", "description": "Description of myKey" }'
       

An invalid key will return 404 Not Found: The specified key doesn't exist.

Delete an existing secure credential

To delete an existing credential in New Relic Synthetics, send a DELETE request to https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials/{key}. Replace the {key} in the following example with the specific key:

curl -v \
     -H 'X-Api-Key:{Admin_User_Key}' \
     -X DELETE https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials/{key}

Please note that if the specified key does not exist, no error will occur.

For more help

Recommendations for learning more: