> 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/external-api-authentication.md).

# External API Authentication

Use this document when Nected calls a **secured external API** through integrations (for example, REST API integrations used in Rules or Workflows).

This guide is specifically for authenticating outbound calls **from Nected to third-party APIs**.\
If you are securing calls to Nected APIs, use [Nected API Key](/nected-docs/security/nected-api-key.md).

### When to use this doc

Use external API authentication when:

* A third-party REST API requires auth (token, key, username/password, or OAuth).
* You want Nected to manage authentication details for integration calls.
* Your Rule/Workflow/API step must invoke protected vendor/internal endpoints.

### Authentication lifecycle in Nected

Nected authentication configurations are created in **Security > Authorization** and then attached to your external API calls.

Operational behavior:

* Nected checks for valid credentials/tokens before API execution.
* For token-based flows, Nected can fetch and reuse tokens according to configuration.
* For expiring tokens, Nected refreshes/re-fetches when required.

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

### Supported authentication methods

Nected supports:

1. Bearer Token
2. API Key
3. Basic Auth
4. OAuth 2.0

### 1. Bearer Token

A token-based mechanism where the API expects a bearer token in the authorization header.

<figure><img src="https://lh4.googleusercontent.com/iqC0Z76jZ1GKESgKrFk5xwePkAIViaRhoT46c7hqMtKuPD61M8jqS-2-nMKD6-VwPE7apgLAlxjEyGfMJKMw4HLk5qsl30a3ArfYOw20CtR90TKI3eCP16pyIDUa74-montwGX52NkP5" alt="Bearer Token configuration modal"><figcaption><p>Bearer Token configuration form</p></figcaption></figure>

#### Bearer Token: Header format

```http
Authorization: Bearer <token>
```

#### Bearer Token: Required fields

* Header (default `Authorization`)
* Token value

#### Bearer Token: Best for

* APIs that already issue static/semi-static bearer tokens
* Standard REST APIs expecting `Authorization: Bearer ...`

#### Bearer Token: Security notes

* Treat bearer tokens as secrets.
* Prefer short-lived tokens where supported by the provider.
* Always use HTTPS.

***

### 2) API Key

#### API Key: What it is

A key-value credential provided by the API owner, passed either in request headers or query parameters.

<figure><img src="https://lh5.googleusercontent.com/SeCmpnm_kVgy_2bUqLUpWv_RZ15p0ONm7IuBC5dqSP0DMBkuRO_3pelERGA1mgVXmpNVRk-__30NXPq9OiCHPwqIIuXuSpbtzZIArz2EJ9sjm-_L5Rtm6DtACgJ4v44UhtFPSGHSiWBO" alt="API Key configuration modal"><figcaption><p>API Key configuration form</p></figcaption></figure>

#### API Key: Format options

Header example:

```http
X-API-Key: <api_key_value>
```

Query example:

```http
GET /resource?api_key=<api_key_value>
```

#### API Key: Required fields

* Key (parameter/header name, for example `X-API-Key` or `api_key`)
* Value (actual secret key)

#### API Key: Best for

* Vendor APIs with key-based authentication
* Internal service APIs that rely on simple machine credentials

#### API Key: Security notes

* Prefer header placement over query params when possible.
* Avoid query-string keys in logs or analytics tools.
* Rotate keys and revoke unused keys regularly.

***

### 3) Basic Auth

#### Basic Auth: What it is

HTTP authentication using username and password encoded into the `Authorization` header.

<figure><img src="/files/8jBfNpVwyHVZvslnw97a" alt=""><figcaption></figcaption></figure>

#### Basic Auth: Header format

```http
Authorization: Basic <base64(username:password)>
```

#### Basic Auth: Required fields

* Username
* Password

#### Basic Auth: Best for

* Legacy APIs that only support username/password auth
* Controlled internal environments where migration is pending

#### Basic Auth: Security notes

* Use only over HTTPS.
* Move to stronger methods (OAuth/API key with rotation) when possible.
* Scope credentials to least privilege.

***

### 4) OAuth 2.0

#### OAuth 2.0: What it is

A standard delegated authorization framework where Nected obtains access tokens from the provider and uses them for API requests.

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

#### OAuth 2.0: Supported grant types

* Client Credentials
* Password Grant
* Authorization Code

#### OAuth 2.0: Common configuration fields

* Grant Type
* Token URL
* Authorization URL (Authorization Code grant)
* Client ID
* Client Secret
* Scope (optional)
* Audience (optional)
* Header Prefix (optional, usually `Bearer`)

#### OAuth 2.0: Best for

* Enterprise and SaaS APIs requiring modern, policy-driven access control
* Integrations where token expiry/refresh handling is needed

#### OAuth 2.0: Security notes

* Prefer Authorization Code or Client Credentials based on provider flow.
* Protect client secrets in a secure secret store.
* Review granted scopes regularly and keep them minimal.

### Choosing the right method

| Method       | Best fit                                   | Security level | Complexity  |
| ------------ | ------------------------------------------ | -------------- | ----------- |
| Bearer Token | Token-auth REST APIs                       | Medium         | Low         |
| API Key      | Vendor/internal key-auth APIs              | Medium         | Low         |
| Basic Auth   | Legacy username/password APIs              | Low-Medium     | Low         |
| OAuth 2.0    | Modern third-party enterprise integrations | High           | Medium-High |

### Setup flow (external API integration)

1. Identify the provider’s required auth method.
2. Create an auth config in **Security > Authorization**.
3. Enter required credentials/endpoints.
4. Attach/select this auth config in the integration/API request step.
5. Test success and failure behavior (invalid credential case).
6. Publish with secrets managed by environment.

### Troubleshooting matrix

| Symptom                           | Likely cause                               | What to check                                                  |
| --------------------------------- | ------------------------------------------ | -------------------------------------------------------------- |
| 401 Unauthorized                  | Wrong/missing credential                   | Header/query placement, key/token value, auth type selection   |
| 403 Forbidden                     | Auth accepted but insufficient permission  | Provider scopes, role policy, endpoint access rights           |
| Works in Postman, fails in Nected | Different auth placement or payload format | Header name, query param key, token prefix, content type       |
| OAuth token errors                | Token URL/client config mismatch           | Grant type, client ID/secret, scope, audience                  |
| Intermittent auth failure         | Token expiry or rotated key                | Refresh behavior, key rotation rollout, cached old credentials |

### Best practices

* Keep separate auth configs per environment (staging vs production) when credentials differ.
* Use descriptive names for auth configs so mapping stays clear in Rules/Workflows.
* Rotate keys/secrets on schedule and after incidents.
* Audit and delete unused authentication configurations.

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