> ## 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 API keys with scoped permissions for your Nango environments.

# API keys

API keys allow programmatic access to your Nango environment. Each environment can have multiple API keys with different permissions, enabling you to follow the principle of least privilege.

## Managing API Keys

API keys are managed in the Nango UI under **Environment Settings > API Keys**.

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

### Creating a 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 a 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 a Key

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

<Tabs>
  <Tab title="Node SDK">
    ```ts theme={null}
    import { Nango } from '@nangohq/node';

    const nango = new Nango({ secretKey: '<YOUR-API-KEY>' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl --request GET \
      --url https://api.nango.dev/connections \
      --header 'Authorization: Bearer <YOUR-API-KEY>'
    ```
  </Tab>
</Tabs>

## Scopes

Scopes control what an 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 actions to production:

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

### Backend Service

For backend services that consume data, trigger actions, and proxy requests:

| Scope                          |
| ------------------------------ |
| `environment:connections:read` |
| `environment:records:read`     |
| `environment:actions:execute`  |
| `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 API key alone won't let an attacker enumerate and access customer data.
</Tip>

### 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 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 functions (syncs and actions)       |
| `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 |

### 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 actions via CLI or API |

### Functions

| Scope                           | Description                  |
| ------------------------------- | ---------------------------- |
| `environment:functions:compile` | Compile function source code |
| `environment:functions:dryrun`  | Dry run function source code |

### Records

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

### Actions

| Scope                         | Description                             |
| ----------------------------- | --------------------------------------- |
| `environment:actions:execute` | Trigger actions and read action results |

### Proxy

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

### Variables

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

### MCP

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