API keys

Tenklo 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 keysCopy Anchor Link

Environment API keys authenticate requests against a single Tenklo 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 keysCopy Anchor Link

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 keyCopy Anchor Link

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 an Environment API keyCopy Anchor Link

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 an Environment API keyCopy Anchor Link

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

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

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

ScopesCopy Anchor Link

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 scopesCopy Anchor Link

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 profilesCopy Anchor Link

Common scope combinations for typical use cases:

Auth (Connect UI)Copy Anchor Link

For backends that create connect sessions for the auth flow:

CI/CD deployCopy Anchor Link

For CI/CD pipelines deploying syncs and actions to production:

Backend serviceCopy Anchor Link

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

Add environment:connections:read_credentials if the service needs access to connection tokens.

Local developmentCopy Anchor Link

For local development, use a Full access key. This is the default key created for each environment.

CLICopy Anchor Link

The Tenklo CLI uses the NANGO_SECRET_KEY_<ENV> environment variable for authentication. Set it to an Environment API key with the required scopes:

For most functions, environment:connections:read is sufficient for nango dryrun — Tenklo 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 scopesCopy Anchor Link

IntegrationsCopy Anchor Link

ConnectionsCopy Anchor Link

Connect SessionsCopy Anchor Link

Agent SessionsCopy Anchor Link

SyncsCopy Anchor Link

DeployCopy Anchor Link

FunctionsCopy Anchor Link

RecordsCopy Anchor Link

LogsCopy Anchor Link

ActionsCopy Anchor Link

ProxyCopy Anchor Link

VariablesCopy Anchor Link

WebhooksCopy Anchor Link

MCPCopy Anchor Link

Account API keysCopy Anchor Link

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 Tenklo dashboard (also available from the profile menu).

Using an Account API keyCopy Anchor Link

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.tenklo.dev/environments \
  --header 'Authorization: Bearer <YOUR-ACCOUNT-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "staging" }'

Account-level APIsCopy Anchor Link

• List environments
• Create an environment
• Delete an environment
• List environment API keys
• Get an environment API key
• Create an environment API key
• Delete an environment API key