Use synthetic monitoring secure credentials APIs

With the 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:

  • See general Synthetics REST API requirements.
  • 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 New Relic 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 'Api-Key:$API_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 account, send a GET request to https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials. For example:

curl -v \
     -H 'Api-Key:$API_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.

curl -v \
     -H 'Api-Key:$API_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 New Relic, send a PUT request to https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials/$KEY.

curl -v \
     -X PUT -H 'Api-Key:$API_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, send a DELETE request to https://synthetics.newrelic.com/synthetics/api/v1/secure-credentials/$KEY.

curl -v \
     -H 'Api-Key:$API_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

If you need more help, check out these support and learning resources: