---
title: Use synthetic monitoring secure credentials APIs
source: https://docs.newrelic.com/docs/apis/synthetics-rest-api/secure-credentials-examples/use-synthetics-secure-credentials-apis
---

With the [synthetic monitoring REST API](https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/manage-synthetics-monitors-rest-api), you can make API calls to change or retrieve [secure credentials](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/using-monitors/secure-credentials-store-credentials-information-scripted-browsers) 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](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/using-monitors/secure-credentials-store-credentials-information-scripted-browsers).

> #### ⚠️ IMPORTANT
>
> You can now manage your secure credentials with our [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-synthetics-tutorial#manage-your-secure-credentials).

## Requirements and rules [#requirements]

For general rules about this feature, see the [secure credentials requirements](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/using-monitors/secure-credentials-store-credentials-information-scripted-browsers#requirements).

API requirements and rules include:

-   See general [synthetic monitoring REST API requirements](https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/manage-synthetics-monitors-rest-api#use-api).
-   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:

````json
{
  "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:

```sh
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:

````sh
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:

```json
{
  "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`.

````SH
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](/docs/apis/synthetics-rest-api/monitor-examples/payload-attributes-synthetics-rest-api#api-attributes) will be a JSON object in the following format:

```json
{
  "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`.

````sh
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`.

````sh
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.

````