# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nected.ai/nected-docs/security/nected-api-key.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.