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:

• 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.

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:

nected-api-key: XXXX-XXXX-XXXX

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.

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.

Note: For the management APIs 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.

2) Copy your Nected API key secret

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

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

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

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

Connect REST API to Nected

Learn how to connect a REST API to Nected and use it to trigger Rules and Workflows

Triggering Rules via API

Learn how to configure and secure Rule APIs for external triggering

Triggering Workflows via API

Learn how to configure and secure Workflow APIs for external triggering