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:
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 credentialslist_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:
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 |
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_credentials + environment:integrations:read + environment:proxy |
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:read | Read a single integration (no credentials) |
environment:integrations:read_credentials | Read a single integration with client credentials |
environment:integrations:write | Create, update, 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:write | Create, update, delete connections and metadata |
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:manage | Update sync frequency, create/delete sync variants |
Deploy
| Scope | Description |
|---|
environment:deploy | Deploy syncs and actions via CLI or API |
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 |
Config
| Scope | Description |
|---|
environment:config:read | Read environment variables and scripts config |
MCP
| Scope | Description |
|---|
environment:mcp | Access the MCP endpoint |
