API keys

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

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

Rotating an Environment API key

To rotate a key:

Create a new key with the same scopes
Update your application to use the new key
Monitor the Last used column on the old key to confirm it’s no longer in use
Delete the old key

Using an Environment API key

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

Node SDK
cURL

import { Nango } from '@nangohq/node';

const nango = new Nango({ apiKey: '<YOUR-ENVIRONMENT-API-KEY>' });

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

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 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:list`	List deployed functions
`environment:functions:read`	Read a single deployed function
`environment:functions:delete`	Delete a deployed function
`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

Logs

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

The environment:logs:read scope is currently only used by the Logs tools in the Management MCP server.

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

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

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

Getting started

Guides

Reference

API keys

API keys

Environment API keys

Managing Environment API keys

Creating an Environment API key

Rotating an Environment API key

Using an Environment API key

Scopes

Credential scopes

Advised profiles

Auth (Connect UI)

CI/CD deploy

Backend service

Local development

CLI

All available scopes

Integrations

Connections

Connect Sessions

Syncs

Deploy

Functions

Records

Logs

Actions

Proxy

Variables

Webhooks

MCP

Account API keys

Using an Account API key

​API keys

​Environment API keys

​Managing Environment API keys

​Creating an Environment API key

​Rotating an Environment API key

​Using an Environment API key

​Scopes

​Credential scopes

​Advised profiles

​Auth (Connect UI)

​CI/CD deploy

​Backend service

​Local development

​CLI

​All available scopes

​Integrations

​Connections

​Connect Sessions

​Syncs

​Deploy

​Functions

​Records

​Logs

​Actions

​Proxy

​Variables

​Webhooks

​MCP

​Account API keys

​Using an Account API key

API keys

Environment API keys

Managing Environment API keys

Creating an Environment API key

Rotating an Environment API key

Using an Environment API key

Scopes

Credential scopes

Advised profiles

Auth (Connect UI)

CI/CD deploy

Backend service

Local development

CLI

All available scopes

Integrations

Connections

Connect Sessions

Syncs

Deploy

Functions

Records

Logs

Actions

Proxy

Variables

Webhooks

MCP

Account API keys

Using an Account API key