> For the complete documentation index, see [llms.txt](https://docs.nected.ai/nected-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nected.ai/nected-docs/security/nected-api-key.md).

# Nected API Key

Use this document when you are calling **Nected APIs** from outside Nected (for example, from your backend, frontend, cron, or any external service) and need to secure those calls.

This guide is specifically for authenticating requests **to Nected**.\
If you want to authenticate calls from Nected to a third-party API, use `External API Authentication (Integrations).md`.

### When to use this doc

Use Nected API key authentication when:

* You trigger a Nected Rule API from an external application.
* You trigger a Nected Workflow API from an external application.
* You expose Nected endpoints as private and want controlled access.

Do not use this doc for third-party API credentials used inside Nected integrations.

### How Nected API authentication works

For Nected APIs, the authentication mode is configured in API settings:

<figure><img src="/files/g14Y8lywKGK3f8XjONwr" alt=""><figcaption></figcaption></figure>

* `None`: endpoint is publicly callable (no Nected API key required).
* `Private`: endpoint requires a valid API key in request headers.

When an endpoint is `Private`, Nected validates the incoming key before execution. Invalid or missing keys return an unauthorized response.

<figure><img src="/files/YB9tKAcLSDvDBHGeNhVm" alt=""><figcaption></figcaption></figure>

### Required header contract

When calling a private Nected API, include:

* Header key: `nected-api-key`
* Header value: your copied secret key from Authorization > API Keys

Example header:

```http
nected-api-key: XXXX-XXXX-XXXX
```

{% hint style="info" %}
**Important**: If you pass an invalid API key when calling a Rule API marked as Private, the request will fail with an **"unauthorized access"** error.
{% endhint %}

### End-to-end setup flow

For most Nected APIs, follow these steps to secure your calls:

#### 1) Configure API Authentication

For user-created Rule or Workflow APIs, open the API settings and set **Authentication** to **Private** to require API key access.

{% hint style="info" %}
**Note:** For [the management APIs](/nected-docs/management-api/audit-log-api.md) where authentication cannot be toggled (always requires API key), this step does not apply. In such cases, the use of the `nected-api-key` is always mandatory.
{% endhint %}

#### 2) Copy your Nected API key secret

Navigate to **Security > Authorization > API Keys** and copy the secret key you wish to use.

<figure><img src="/files/CSXKCf6c8VOCL6O8sxoZ" alt=""><figcaption></figcaption></figure>

#### 3) Add `nected-api-key` to the API request headers

Include the copied API key in the `nected-api-key` header in any external service, client, or integration making the request.

#### 4) Test key validation behavior

Test your connection with a valid key to ensure successful authentication. Also verify the response when an invalid or missing key is provided to confirm unauthorized access is correctly enforced.

### Request examples

#### cURL example

```bash
curl -X POST "https://<your-nected-endpoint>" \
  -H "Content-Type: application/json" \
  -H "nected-api-key: XXXX-XXXX-XXXX" \
  -d '{
    "input": {
      "customerId": "CUST-1001"
    }
  }'
```

#### JavaScript (fetch) example

```javascript
const response = await fetch("https://<your-nected-endpoint>", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "nected-api-key": process.env.NECTED_API_KEY
  },
  body: JSON.stringify({
    input: { customerId: "CUST-1001" }
  })
});

if (!response.ok) {
  throw new Error(`Nected API call failed: ${response.status}`);
}

const data = await response.json();
```

### Key management and security best practices

* Store `nected-api-key` values in a secret manager or environment variables; never hardcode.
* Rotate keys on a regular cadence and immediately if exposure is suspected.
* Use least-privilege distribution: share keys only with systems that must call private Nected APIs.
* Restrict logs to avoid printing full keys (mask all but last 3-4 characters).
* Always call Nected APIs over HTTPS.

### Troubleshooting

#### Unauthorized access

Check:

* API authentication mode is `Private` and you are sending `nected-api-key`.
* Header name is exactly `nected-api-key` (case sensitivity may vary by client/proxy, but name must match).
* Secret value is current (not rotated/revoked).

#### Endpoint works in one service but fails in another

Check:

* Proxy/API gateway is forwarding custom headers.
* Environment variable is loaded in that runtime.
* Request path and method match the published Nected API trigger.

#### Intermittent failures after rotation

Check:

* Old key cache in long-running services.
* Deployment completed across all services using the key.
* Secret sync delay in your deployment platform.

### Related documentation

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Connect REST API to Nected</strong></td><td>Learn how to connect a REST API to Nected and use it to trigger Rules and Workflows</td><td><a href="/files/E7Le4pvkcRgJ8dtrULaq">/files/E7Le4pvkcRgJ8dtrULaq</a></td><td><a href="/pages/XNTuWs0PYrWHC7O0oIab">/pages/XNTuWs0PYrWHC7O0oIab</a></td></tr><tr><td><strong>Triggering Rules via API</strong></td><td>Learn how to configure and secure Rule APIs for external triggering</td><td><a href="/files/LsGGWoXhFmbZOHlBhyE1">/files/LsGGWoXhFmbZOHlBhyE1</a></td><td><a href="/pages/RmVsCRpL9BVLStXl4Bhs">/pages/RmVsCRpL9BVLStXl4Bhs</a></td></tr><tr><td><strong>Triggering Workflows via API</strong></td><td>Learn how to configure and secure Workflow APIs for external triggering</td><td><a href="/files/TLd2kDG0gVGRqz8jFIHH">/files/TLd2kDG0gVGRqz8jFIHH</a></td><td><a href="/pages/M8Zpbv6n8P7ZirBRdXZe">/pages/M8Zpbv6n8P7ZirBRdXZe</a></td></tr></tbody></table>