> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Manage Environment and Account API keys with scoped permissions for Nango.

Nango has two API key types. They are not interchangeable.

* **Environment API keys** grant access to a single environment (integrations, connections, functions, records, proxy, and related APIs). Each key can have full access or a custom set of environment scopes.
* **Account API keys** grant access to account-level APIs only. They do not grant access to any environment.

Most integrations use Environment API keys. Account API keys are for account-level automation and are managed separately.

## Environment API keys

Environment API keys authenticate requests against a single Nango environment. Use them with environment-level APIs for integrations, connections, functions, records, and proxy requests.

Manage Environment API keys under **Environment Settings > API Keys**.

### Managing Environment API keys

Each environment comes with a **Default - Full access** key that grants access to all environment API endpoints. You can create additional keys with restricted scopes for specific use cases.

### Creating an Environment API key

1. Go to **Environment Settings > API Keys**
2. Click **Create API Key**
3. Enter a display name (e.g., "CI Deploy Key", "Backend service")
4. Choose **Full access** or **Custom** permissions — custom lets you pick individual scopes
5. The key is created immediately and can be revealed and copied from the key list

### Rotating an Environment API key

To rotate a key:

1. Create a new key with the same scopes
2. Update your application to use the new key
3. Monitor the **Last used** column on the old key to confirm it's no longer in use
4. Delete the old key

### Using an Environment API key

Pass the Environment API key as a Bearer token in the `Authorization` header:

> [tab] Node SDK
>
> ```ts theme={null}
> import { Nango } from '@nangohq/node';
>
> const nango = new Nango({ apiKey: '<YOUR-ENVIRONMENT-API-KEY>' });
> ```

> [tab] cURL
>
> ```bash theme={null}
> curl --request GET \
>   --url https://api.nango.dev/connections \
>   --header 'Authorization: Bearer <YOUR-ENVIRONMENT-API-KEY>'
> ```

### Scopes

Scopes control what an Environment API key can access. When creating a key with **Custom** permissions, you select which scopes to grant. A key without a specific scope will receive a `403 Forbidden` response when trying to access a protected endpoint.

#### Credential scopes

Some resources (Integrations and Connections) have sensitive credential data. Access to this data is controlled by dedicated `_credentials` scopes:

* `list` / `read` — returns the resource **without** sensitive credentials
* `list_credentials` / `read_credentials` — returns the resource **with** credentials (access tokens, client secrets, etc.)

The `_credentials` scopes are supersets — selecting `read_credentials` automatically includes `read` access. You don't need to select both.

| Resource | Without credentials | With credentials |
| - | - | - |
| **Connections** | Connection metadata, tags, status | + access/refresh tokens |
| **Integrations** | Provider, display name, config | + client ID and client secret |

### Advised profiles

Common scope combinations for typical use cases:

#### Auth (Connect UI)

For backends that create connect sessions for the auth flow:

| Scope |
| - |
| `environment:connect_sessions:write` |

#### CI/CD deploy

For CI/CD pipelines deploying syncs and tools to production:

| Scope |
| - |
| `environment:deploy` |

#### Backend service

For backend services that consume data, call tools, and proxy requests:

| Scope |
| - |
| `environment:connections:read` |
| `environment:records:read` |
| `environment:tools:call` |
| `environment:syncs:execute` |
| `environment:proxy` |

Add `environment:connections:read_credentials` if the service needs access to connection tokens.

> [!TIP]
>
> For extra security, avoid when possible granting `environment:connections:list` to backend services. Without it, connection IDs act as connection-specific secrets — a leaked Environment API key alone won't let an attacker enumerate and access customer data.

#### Local development

For local development, use a **Full access** key. This is the default key created for each environment.

### CLI

The Nango CLI uses the `NANGO_SECRET_KEY_<ENV>` environment variable for authentication. Set it to an Environment API key with the required scopes:

| CLI Command | Required Scope |
| - | - |
| `nango deploy` | `environment:deploy` |
| `nango dryrun` | `environment:connections:read` + `environment:integrations:read` + `environment:proxy` |

For most functions, `environment:connections:read` is sufficient for `nango dryrun` — Nango injects credentials into the proxy automatically, so the function does not need them in its response. Upgrade to `environment:connections:read_credentials` when the function reads credential data from the connection, including:

* accessing `connection.credentials` directly (e.g. `nango.getConnection().credentials`)
* calling `nango.getToken()` — returns the access token from `connection.credentials`
* calling `nango.getRawTokenResponse()` — returns `connection.credentials.raw`

Without `read_credentials`, these helpers return empty values because the API strips the `credentials` field from the response.

The **Default - Full access** key that comes with each environment already has all required scopes for deploying and dry-running. For production CI/CD pipelines, consider creating a dedicated key with only the `environment:deploy` scope to follow the principle of least privilege.

### All available scopes

#### Integrations

| Scope | Description |
| - | - |
| `environment:integrations:list` | List integrations (no credentials) |
| `environment:integrations:list_credentials` | List integrations with client credentials |
| `environment:integrations:list_functions` | List deployed function configuration (syncs and tools) |
| `environment:integrations:read` | Read a single integration (no credentials) |
| `environment:integrations:read_credentials` | Read a single integration with client credentials |
| `environment:integrations:create` | Create integrations |
| `environment:integrations:update` | Update integrations |
| `environment:integrations:delete` | Delete integrations |

#### Connections

| Scope | Description |
| - | - |
| `environment:connections:list` | List connections (no credentials) |
| `environment:connections:list_credentials` | List connections with access/refresh tokens |
| `environment:connections:read` | Read a single connection (no credentials) |
| `environment:connections:read_credentials` | Read a single connection with access/refresh tokens |
| `environment:connections:create` | Create connections |
| `environment:connections:update` | Update connections and metadata |
| `environment:connections:delete` | Delete connections |

#### Connect Sessions

| Scope | Description |
| - | - |
| `environment:connect_sessions:write` | Create and reconnect sessions for the Connect UI auth flow |

#### Agent Sessions

> [!NOTE]
>
> Agent sessions are experimental. The endpoints and this scope are likely to change, including in breaking ways, until the feature is generally available. See the [agent sessions guide](https://nango.dev/docs/guides/agent-sessions.md).

| Scope | Description |
| - | - |
| `environment:agent_sessions:write` | Create agent sessions |

#### Syncs

| Scope | Description |
| - | - |
| `environment:syncs:read` | Read sync status |
| `environment:syncs:execute` | Trigger, pause, start syncs |
| `environment:syncs:update` | Update sync connection frequency |
| `environment:syncs:variant:create` | Create sync variants |
| `environment:syncs:variant:delete` | Delete sync variants |

#### Deploy

| Scope | Description |
| - | - |
| `environment:deploy` | Deploy syncs and tools via CLI or API |

#### Functions

| Scope | Description |
| - | - |
| `environment:functions:list` | List available functions |
| `environment:functions:read` | Read a single available function |
| `environment:functions:delete` | Delete a deployed function |
| `environment:functions:compile` | Compile function source code |
| `environment:functions:dryrun` | Dry run function source code |

> [!WARNING]
>
> When a key with `environment:functions:dryrun` starts a dryrun, the sandbox token inherits all of the parent key's scopes and additionally grants `environment:connections:read`, `environment:integrations:read`, and `environment:proxy` for the core SDK features to work while running a function.

#### Records

| Scope | Description |
| - | - |
| `environment:records:read` | Read synced records |
| `environment:records:write` | Prune records |

#### Logs

| Scope | Description |
| - | - |
| `environment:logs:read` | Read log operations and messages |

> [!NOTE]
>
> The `environment:logs:read` scope is currently only used by the [Logs tools in the Management MCP server](https://nango.dev/docs/reference/backend/management-mcp.md#logs).

#### Tools

| Scope | Description |
| - | - |
| `environment:tools:call` | Call tools. Also covers deprecated actions: trigger them and read their results |

> [!NOTE]
>
> `environment:tools:call` replaces the deprecated `environment:actions:execute` scope. Existing keys that hold `environment:actions:execute` or `environment:actions:*` keep working and grant `environment:tools:call`.

#### Proxy

| Scope | Description |
| - | - |
| `environment:proxy` | Send proxy requests to external APIs through Nango |

#### Variables

| Scope | Description |
| - | - |
| `environment:variables:read` | Read environment variables |

#### Webhooks

| Scope | Description |
| - | - |
| `environment:webhook_signing_key:rotate` | Rotate the webhook signing key |

#### MCP

| Scope | Description |
| - | - |
| `environment:mcp` | Access the MCP endpoint |

## Account API keys

Account API keys authenticate requests against account-level APIs. They do not grant access to any environment.

They always have full account access and can only be managed by account administrators.

Manage Account API keys from [Account API keys](https://app.nango.dev/api-keys) in the Nango dashboard (also available from the profile menu).

### Using an Account API key

Pass the Account API key as a Bearer token in the `Authorization` header. Account API keys cannot call environment-level endpoints — use an Environment API key for those.

```bash theme={null}
curl --request POST \
  --url https://api.nango.dev/environments \
  --header 'Authorization: Bearer <YOUR-ACCOUNT-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "staging" }'
```

### Account-level APIs

* [List environments](https://nango.dev/docs/reference/backend/http-api/environments/list.md)
* [Get an environment](https://nango.dev/docs/reference/backend/http-api/environments/get.md)
* [Create an environment](https://nango.dev/docs/reference/backend/http-api/environments/create.md)
* [Delete an environment](https://nango.dev/docs/reference/backend/http-api/environments/delete.md)
* [List environment API keys](https://nango.dev/docs/reference/backend/http-api/environments/list-api-keys.md)
* [Get an environment API key](https://nango.dev/docs/reference/backend/http-api/environments/get-api-key.md)
* [Create an environment API key](https://nango.dev/docs/reference/backend/http-api/environments/create-api-key.md)
* [Delete an environment API key](https://nango.dev/docs/reference/backend/http-api/environments/delete-api-key.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.