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

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

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

Node SDK
cURL

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

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

curl --request GET \
  --url https://api.nango.dev/connections \
  --header 'Authorization: Bearer <YOUR-API-KEY>'

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.

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.

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

MCP

Scope	Description
`environment:mcp`	Access the MCP endpoint

Getting started

Guides

Reference

API keys

API keys

Managing API Keys

Creating a Key

Rotating a Key

Using a 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

MCP

​API keys

​Managing API Keys

​Creating a Key

​Rotating a Key

​Using a 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

​MCP

API keys

Managing API Keys

Creating a Key

Rotating a Key

Using a 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

MCP