Use Nango as a Credential Store

Nango is an excellent choice for both development and production environments, particularly when working with OAuth2.1/PKCE flows and complex integrations.

To get started, first set up Nango either through cloud or local deployment, then create your credential, and finally consume the credential through the TypeScript SDK.

Nango setup option 1: Nango Cloud

Step 1: Create a Nango account

Sign up here.

Step 2: Save your Nango secret key

After creating your Nango account, navigate to Environment Settings in your dashboard and copy the secret key.

Step 3: Configure your root .env file

NANGO_SECRET_KEY=your_nango_secret_key

Restart your dev server to load the new environment variable:

pnpm dev

Step 4: Create a new credential in the Visual Builder using Nango

Nango setup option 2: Nango local

Automated Setup (Recommended)

Run the following from your project root:

pnpm setup-dev:optional

This:

• Clones agents-optional-local-dev into .optional-services/ if not already present
• Starts Nango, SigNoz, OTEL Collector, and Jaeger via Docker Compose
• Generates a Nango secret key and writes it to your .env (re-uses an existing key if already set)
• Sets NANGO_SERVER_URL, PUBLIC_NANGO_SERVER_URL, and PUBLIC_NANGO_CONNECT_BASE_URL

Restart your dev server after setup completes:

pnpm dev

Then create a credential in the Visual Builder using Nango Store.

Use pnpm optional:status to check service health, pnpm optional:stop to stop optional services, or pnpm optional:reset to start fresh.

Manual Setup

If you prefer manual setup:

Step 1: Clone the optional services repository

git clone https://github.com/inkeep/agents-optional-local-dev .optional-services
cd .optional-services

Step 2: Configure the .optional-services/.env

Nango requires an encryption key for credential storage. Create the .env from the template:

cp .env.docker.example .env && \
  nango_encryption_key=$(openssl rand -base64 32) && \
  nango_dashboard_password=$(openssl rand -base64 8) && \
  tmp_file=$(mktemp) && \
  sed \
    -e "s|<REPLACE_WITH_NANGO_ENCRYPTION_KEY>|$nango_encryption_key|" \
    -e "s|<REPLACE_WITH_NANGO_DASHBOARD_PASSWORD>|$nango_dashboard_password|" \
    .env > "$tmp_file" && \
  mv "$tmp_file" .env && \
  echo ".env created with auto-generated NANGO_ENCRYPTION_KEY and NANGO_DASHBOARD_PASSWORD"

Step 3: Start Nango Services

Inside .optional-services, start Nango:

docker compose --profile nango up -d

Step 4: Save your Nango secret key

1. Open Nango at http://localhost:3050
2. Navigate to Environment Settings and copy the secret key

Step 5: Configure your root .env file

In your root project directory (not inside .optional-services/), update your .env file:

NANGO_SECRET_KEY=your_nango_secret_key
NANGO_SERVER_URL=http://localhost:3050
PUBLIC_NANGO_SERVER_URL=http://localhost:3050
PUBLIC_NANGO_CONNECT_BASE_URL=http://localhost:3051

Restart your dev server:

pnpm dev

Step 6: Create a credential in the Visual Builder

Create a credential in the Visual Builder using Nango Store.

Referencing credentials in SDK

Once you have created a credential in the Visual Builder, you can reference it in the TypeScript SDK for both Bearer Authentication and OAuth2.1/PKCE.

Here is an example of how to reference a credential in the TypeScript SDK for both Bearer Authentication and OAuth2.1/PKCE.

Credential Configuration