Skip to main content

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

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

​
Advised Profiles

Common scope combinations for typical use cases:

​
Auth (Connect UI)

For backends that create connect sessions for the auth flow:

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

​
Connections

​
Connect Sessions

​
Syncs

​
Deploy

​
Functions

​
Records

​
Logs

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

​
Actions

​
Proxy

​
Variables

​
MCP