// Use when adding support for a new Nango provider - configures provider in providers.yaml, creates documentation (main page, setup guide, connect guide), and updates docs.json following established patterns
Use when fixing CJS/ESM module issues in Nango integrations after zero-yaml migration - covers import path fixes, creating ESM wrappers for CJS vendor modules, and restoring commented-out code
Use when testing Nango syncs locally - runs dry-run command with proper parameters for integration testing without affecting production data
Use when creating, improving, or troubleshooting Claude Code subagents. Expert guidance on agent design, system prompts, tool access, model selection, and best practices for building specialized AI assistants.
Use when creating, improving, or troubleshooting Claude Code subagents. Expert guidance on agent design, system prompts, tool access, model selection, and best practices for building specialized AI assistants.
Expert guidance for creating effective Cursor IDE rules with best practices, patterns, and examples
Best practices for structuring prpm.json package manifests with required fields, tags, organization, and multi-package management
| name | adding-nango-provider-support |
| description | Use when adding support for a new Nango provider - configures provider in providers.yaml, creates documentation (main page, setup guide, connect guide), and updates docs.json following established patterns |
Add support for new Nango providers by configuring the provider in providers.yaml first, then creating documentation following the established structure: main integration page with 4-step quickstart, separate setup guide (for OAuth), connect guide (for non-OAuth or OAuth with connectionConfig), and proper configuration in docs.json.
| File | Path | Purpose |
|---|---|---|
| Main page | docs/api-integrations/[slug].mdx | Quickstart + guide links + syncs section |
| Setup guide | docs/api-integrations/[slug]/how-to-register-your-own-[slug]-oauth-app.mdx | OAuth app registration steps (OAuth2 only) |
| Connect guide | docs/api-integrations/[slug]/connect.mdx | Connection UI guide (all non-OAuth2, and OAuth2 with connectionConfig) |
| Navigation | docs/docs.json | Add to "APIs & Integrations" group |
| Provider config | packages/providers/providers.yaml | Add docs and setup_guide_url |
Note: Pre-built syncs snippets are automatically generated by an automated script - you do not need to create them manually.
IMPORTANT: Always start by editing packages/providers/providers.yaml first. This file contains all the authentication configuration and connection details needed for the integration.
Before creating documentation, you must add or update the provider entry in packages/providers/providers.yaml. This file contains all authentication configuration.
IMPORTANT: Providers must be added in alphabetical order by their slug (provider key). Use the existing entries as a reference to find the correct insertion point.
The following auth modes are supported:
slab:
display_name: Slab
categories:
- productivity
- knowledge-base
auth_mode: API_KEY
proxy:
base_url: https://api.slab.com
headers:
authorization: Token ${apiKey}
content-type: application/json
verification:
method: POST
headers:
content-type: application/json
endpoints:
- /v1/graphql
docs: https://nango.dev/docs/api-integrations/slab
setup_guide_url: https://nango.dev/docs/api-integrations/slab/how-to-obtain-your-slab-api-key
docs_connect: https://nango.dev/docs/api-integrations/slab/connect
credentials:
apiKey:
type: string
title: API Token
description: Your Slab API token
secret: true
doc_section: '#step-1-generating-your-slab-api-token'
acuity-scheduling:
display_name: Acuity Scheduling
categories:
- productivity
auth_mode: OAUTH2
authorization_url: https://acuityscheduling.com/oauth2/authorize
token_url: https://acuityscheduling.com/oauth2/token
default_scopes:
- api-v1
proxy:
base_url: https://acuityscheduling.com/api/v1
docs: https://nango.dev/docs/integrations/all/acuity-scheduling
setup_guide_url: https://nango.dev/docs/integrations/all/acuity-scheduling/how-to-register-your-own-acuity-scheduling-oauth-app
accelo:
display_name: Accelo
categories:
- invoicing
- ticketing
auth_mode: OAUTH2
authorization_url: https://${connectionConfig.subdomain}.api.accelo.com/oauth2/v0/authorize
token_url: https://${connectionConfig.subdomain}.api.accelo.com/oauth2/v0/token
scope_separator: ','
authorization_params:
response_type: code
token_params:
grant_type: authorization_code
refresh_params:
grant_type: refresh_token
proxy:
base_url: https://${connectionConfig.subdomain}.api.accelo.com
docs: https://nango.dev/docs/integrations/all/accelo
setup_guide_url: https://nango.dev/docs/integrations/all/accelo/how-to-register-your-own-accelo-oauth-app
docs_connect: https://nango.dev/docs/integrations/all/accelo/connect
connection_config:
subdomain:
type: string
title: Accelo Domain
description: The subdomain of your Accelo account
pattern: '^[a-z0-9_-]+$'
example: domain
suffix: .api.accelo.com
prefix: https://
private-api-basic:
display_name: Private API (Basic Auth)
auth_mode: BASIC
proxy:
base_url: https://my-private-api
docs: https://nango.dev/docs/integrations/all/private-api-basic
docs_connect: https://nango.dev/docs/integrations/all/private-api-basic/connect
credentials:
username:
type: string
title: Username
description: Your username
password:
type: string
title: Password
description: Your password
adobe-umapi:
display_name: UMAPI (Adobe User Management API)
categories:
- other
auth_mode: OAUTH2_CC
token_url: https://ims-na1.adobelogin.com/ims/token/v2
scope_separator: ','
token_params:
grant_type: client_credentials
proxy:
headers:
x-api-key: ${connectionConfig.clientId}
retry:
after:
- 'retry-after'
base_url: https://usermanagement.adobe.io
docs: https://nango.dev/docs/integrations/all/adobe-umapi
docs_connect: https://nango.dev/docs/integrations/all/adobe-umapi/connect
connection_config:
clientId:
type: string
title: ''
description: ''
automated: true
garmin:
display_name: Garmin
categories:
- health
auth_mode: OAUTH1
request_url: https://connectapi.garmin.com/oauth-service/oauth/request_token
authorization_url: https://connect.garmin.com/oauthConfirm
token_url: https://connectapi.garmin.com/oauth-service/oauth/access_token
signature_method: 'HMAC-SHA1'
proxy:
base_url: https://apis.garmin.com
docs: https://nango.dev/docs/integrations/all/garmin
jamf-basic:
display_name: Jamf Pro (Basic Auth)
categories:
- other
auth_mode: TWO_STEP
proxy:
base_url: https://${connectionConfig.instance}.jamfcloud.com
headers:
authorization: Bearer ${accessToken}
token_url: https://${connectionConfig.instance}.jamfcloud.com/api/v1/auth/token
token_headers:
authorization: Basic ${base64(${credentials.username}:${credentials.password})}
token_response:
token: token
token_expiration: expires
token_expiration_strategy: expireAt
docs: https://nango.dev/docs/integrations/all/jamf-basic
docs_connect: https://nango.dev/docs/integrations/all/jamf-basic/connect
connection_config:
instance:
type: string
title: Jamf Pro Instance
description: Your Jamf Pro instance
example: example
prefix: https://
suffix: .jamfcloud.com
order: 1
credentials:
username:
type: string
title: Username
description: Your Jamf Pro username
password:
type: string
title: Password
description: Your Jamf Pro password
secret: true
ghost:
display_name: Ghost
categories:
- cms
auth_mode: JWT
signature:
protocol: HMAC
token:
signing_key: ${credentials.privateKey.secret}
expires_in_ms: 300000
header:
alg: HS256
kid: ${credentials.privateKey.id}
payload:
aud: /admin/
proxy:
headers:
accept: application/json
accept-version: ${connectionConfig.version}
authorization: Ghost ${accessToken}
base_url: https://${connectionConfig.adminDomain}/ghost/api/admin/
verification:
method: GET
headers:
content-type: application/json
endpoints:
- /site
docs: https://nango.dev/docs/integrations/all/ghost
docs_connect: https://nango.dev/docs/integrations/all/ghost/connect
connection_config:
adminDomain:
type: string
title: Admin Domain
description: Your Ghost admin domain
format: hostname
prefix: https://
example: ghost.example.com
doc_section: '#step-1-finding-your-admin-domain'
version:
type: string
title: API Version
description: The Ghost API version
example: v5.0
doc_section: '#step-2-finding-your-api-version'
credentials:
privateKey:
type: object
title: Private Key
description: Your Ghost private key
properties:
id:
type: string
title: Key ID
secret:
type: string
title: Key Secret
secret: true
doc_section: '#step-3-generating-your-private-key'
emarsys:
display_name: Emarsys
categories:
- marketing
auth_mode: SIGNATURE
signature:
protocol: WSSE
proxy:
base_url: https://api.emarsys.net
headers:
content-type: application/json
x-wsse: ${accessToken}
verification:
method: GET
headers:
content-type: application/json
endpoints:
- /api/v2/settings
retry:
at:
- 'x-ratelimit-reset'
token:
expires_in_ms: 300000
docs: https://nango.dev/docs/integrations/all/emarsys
docs_connect: https://nango.dev/docs/integrations/all/emarsys/connect
credentials:
username:
type: string
title: Username
description: Your Emarsys username
secretKey:
type: string
title: Secret Key
description: Your Emarsys secret key
secret: true
When adding a provider, you must specify one or more categories from the following allowed list:
accountinganalyticsatsbankingcmscommunicationcrmdesigndev-toolse-commerceerpgaminghrinvoicingknowledge-baselegalmarketingmcpotherpaymentpopularproductivitysearchsocialsportsstoragesupportsurveysticketingvideoImportant: Only use categories from this list. Do not create new categories.
display_name: Required - The display name of the providercategories: Required - Array of categories from the allowed list aboveauth_mode: Required - One of the auth modes listed aboveauthorization_url: Required for OAUTH2, OAUTH1 - The OAuth authorization URLtoken_url: Required for OAUTH2, OAUTH2_CC, OAUTH1, TWO_STEP, APP - The token endpoint URLproxy.base_url: Required - The base URL for API requestsproxy.headers: Optional - Headers to include in requests (use ${apiKey}, ${accessToken}, etc.)proxy.verification: Optional - Only required for API_KEY, BASIC, and JWT auth modes. Used to verify credentials during connection creation. See verification guidelines below.connection_config: Optional - Configuration values end users need to provide (subdomain, domain, etc.)credentials: Optional - Credential fields (apiKey, username, password, etc.)docs: Required - Link to main documentation pagesetup_guide_url: Required for OAUTH2 - Link to OAuth app registration guidedocs_connect: Required for non-OAuth2 OR OAuth2 with connectionConfig - Link to connect.mdx guideIMPORTANT: Only API_KEY, BASIC, and JWT auth modes require a verification configuration in the proxy section. Other auth modes (OAUTH2, OAUTH1, OAUTH2_CC, TWO_STEP, SIGNATURE) do not need verification.
When configuring verification:
/me, /user, /profile, /account)limit parameter, set it to 1 to reduce response size and speed up connection creationExample verification configuration:
proxy:
base_url: https://api.example.com
headers:
authorization: Bearer ${apiKey}
verification:
method: GET
headers:
content-type: application/json
endpoints:
- /v1/me?limit=1 # Simple endpoint with limit parameter
Note: For OAuth-based auth modes, credential verification happens automatically during the OAuth flow, so no explicit verification configuration is needed.
| Auth Mode | Main Page | Setup Guide | Connect Guide |
|---|---|---|---|
| API_KEY | ✅ | ❌ | ✅ (connect.mdx) |
| BASIC | ✅ | ❌ | ✅ (connect.mdx) |
| OAUTH2 (no connectionConfig) | ✅ | ✅ (how-to-register) | ❌ |
| OAUTH2 (with connectionConfig) | ✅ | ✅ (how-to-register) | ✅ (connect.mdx) |
| OAUTH2_CC | ✅ | ❌ | ✅ (connect.mdx) |
| OAUTH1 | ✅ | ✅ (how-to-register) | ❌ |
| TWO_STEP | ✅ | ❌ | ✅ (connect.mdx) |
| JWT | ✅ | ❌ | ✅ (connect.mdx) |
| SIGNATURE | ✅ | ❌ | ✅ (connect.mdx) |
Summary:
[slug].mdx)how-to-register-your-own-[slug]-oauth-app.mdx)connect.mdxconnect.mdxBefore creating docs, gather:
productivity, crm, popular)Path: docs/api-integrations/[slug].mdx
---
title: '[Integration Name]'
sidebarTitle: '[Integration Name]'
description: 'Integrate your application with the [Integration Name] API'
---
## 🚀 Quickstart
Connect to [Integration Name] with Nango and see data flow in 2 minutes.
<Steps>
<Step title="Create the integration">
In Nango ([free signup](https://app.nango.dev)), go to [Integrations](https://app.nango.dev/dev/integrations) -> _Configure New Integration_ -> _[Integration Name]_.
</Step>
<Step title="Authorize [Integration Name]">
Go to [Connections](https://app.nango.dev/dev/connections) -> _Add Test Connection_ -> _Authorize_, then log in to [Integration Name]. Later, you'll let your users do the same directly from your app.
</Step>
<Step title="Call the [Integration Name] API">
Let's make your first request to the [Integration Name] API. Replace the placeholders below with your [secret key](https://app.nango.dev/dev/environment-settings), [integration ID](https://app.nango.dev/dev/integrations), and [connection ID](https://app.nango.dev/dev/connections):
<Tabs>
<Tab title="cURL">
```bash
curl "https://api.nango.dev/proxy/[example-endpoint]" \
-H "Authorization: Bearer <NANGO-SECRET-KEY>" \
-H "Provider-Config-Key: <INTEGRATION-ID>" \
-H "Connection-Id: <CONNECTION-ID>"
```
</Tab>
<Tab title="Node">
Install Nango's backend SDK with `npm i @nangohq/node`. Then run:
```typescript
import { Nango } from '@nangohq/node';
const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });
const res = await nango.get({
endpoint: '/[example-endpoint]',
providerConfigKey: '<INTEGRATION-ID>',
connectionId: '<CONNECTION-ID>'
});
console.log(res.data);
```
</Tab>
</Tabs>
Or fetch credentials with the [Node SDK](/reference/sdks/node#get-a-connection-with-credentials) or [API](/reference/api/connection/get).
✅ You're connected! Check the [Logs](https://app.nango.dev/dev/logs) tab in Nango to inspect requests.
</Step>
<Step title="Implement Nango in your app">
Follow our [quickstart](/getting-started/quickstart/embed-in-your-app) to integrate Nango in your app.
To obtain your own production credentials, follow the setup guide linked below.
</Step>
</Steps>
## 📚 [Integration Name] Integration Guides
Nango-maintained guides for common use cases.
- [How to register your own [Integration Name] OAuth app](/api-integrations/[slug]/how-to-register-your-own-[slug]-oauth-app)
Register an OAuth app with [Integration Name] and obtain credentials to connect it to Nango
- [How do I link my [Integration Name] account?](/api-integrations/[slug]/connect)
Learn how to authenticate with [Integration Name] and link your account
*Include this line only if connect.mdx exists (for non-OAuth2 or OAuth2 with connectionConfig)*
Official docs: [[Integration Name] API docs]([API_DOCS_URL])
## 🧩 Pre-built syncs & actions for [Integration Name]
Enable them in your dashboard. [Extend and customize](/implementation-guides/building-integrations/extend-reference-implementation) to fit your needs.
---
Path: docs/api-integrations/[slug]/how-to-register-your-own-[slug]-oauth-app.mdx
---
title: 'How to register your own [Integration Name] OAuth app'
sidebarTitle: '[Integration Name] Setup'
description: 'Register an OAuth app with [Integration Name] and connect it to Nango'
---
This guide shows you how to register your own app with [Integration Name] to obtain your OAuth credentials (client id & secret). These are required to let your users grant your app access to their [Integration Name] account.
<Steps>
<Step title="Create a developer account">
Go to [[Integration Name] Developer Portal]([DEVELOPER_PORTAL_URL]) and sign up for a developer account.
</Step>
<Step title="Create a new application">
1. Navigate to your applications/apps dashboard
2. Click "Create New App" or similar
3. Fill in the required details (app name, description)
</Step>
<Step title="Configure OAuth settings">
1. In your app settings, find OAuth or authentication settings
2. Add the Nango callback URL: `https://api.nango.dev/oauth/callback`
3. Select the scopes your application needs
</Step>
<Step title="Get your credentials">
Copy your **Client ID** and **Client Secret** from the app settings. You'll need these when configuring the integration in Nango.
</Step>
<Step title="Next">
Follow the [_Quickstart_](/getting-started/quickstart) to connect your first account.
</Step>
</Steps>
For more details, see [[Integration Name]'s OAuth documentation]([OAUTH_DOCS_URL]).
---
Path: docs/api-integrations/[slug]/connect.mdx
Use this template for API_KEY, BASIC, OAUTH2_CC, TWO_STEP, JWT, SIGNATURE, and OAuth2 with connectionConfig.
---
title: [Integration Name] - How do I link my account?
sidebarTitle: [Integration Name]
---
# Overview
To authenticate with [Integration Name], you will need:
1. **[Credential/Config Name]** - [Description of what this is].
This guide will walk you through [finding/generating] your **[Credential/Config Name]** within [Integration Name].
### Prerequisites:
- You must have a [Integration Name] account [and any specific requirements].
### Instructions:
#### Step 1: [Finding/Generating] your [Integration Name] [Credential/Config Name]
1. Sign in to your [[Integration Name]]([URL]) account.
2. [Step-by-step instructions for finding/generating the credential or config value]
3. [Continue with detailed steps]
<img src="/api-integrations/[slug]/[image-name].png"/>
[Add more steps as needed]
#### Step 2: Enter credentials in the Connect UI
Once you have your **[Credential/Config Name]**:
1. Open the form where you need to authenticate with [Integration Name].
2. Enter your **[Credential/Config Name]** in the respective field.
3. Submit the form, and you should be successfully authenticated.
<img src="/api-integrations/[slug]/form.png" style={{maxWidth: "450px" }}/>
You are now connected to [Integration Name].
Example (Slab - API_KEY):
---
title: Slab - How do I link my account?
sidebarTitle: Slab
---
# Overview
To authenticate with Slab, you will need:
1. **API Token** - Your Slab API token for authentication.
This guide will walk you through generating your **API Token** within Slab.
### Prerequisites:
- You must have a Slab account with a Business or Enterprise plan
### Instructions:
#### Step 1: Generating your Slab API Token
1. Sign in to your [Slab](https://slab.com/) account.
2. Click your team name in the top-left corner of the sidebar.
3. Click **Team settings** in the dropdown menu.
<img src="/api-integrations/slab/settings.png"/>
4. Navigate to **Developer** in the left-hand sidebar.
5. You can copy your **API Token**.
<img src="/api-integrations/slab/api.png"/>
#### Step 2: Enter credentials in the Connect UI
Once you have your **API Token**:
1. Open the form where you need to authenticate with Slab.
2. Enter your **API Token** in the respective field.
3. Submit the form, and you should be successfully authenticated.
<img src="/api-integrations/slab/form.png" style={{maxWidth: "450px" }}/>
You are now connected to Slab.
Add to the "APIs & Integrations" group in alphabetical order:
{
"group": "APIs & Integrations",
"pages": [
// ... other integrations alphabetically
"api-integrations/[slug]",
// ... more integrations
]
}
Important:
IMPORTANT: Providers must be added in alphabetical order by their slug (provider key). Find the correct insertion point by searching for providers that come before and after your new provider alphabetically.
Add or update the provider entry with docs URLs:
For OAuth2 (without connectionConfig):
[slug]:
display_name: [Integration Name]
# ... other provider config ...
docs: https://nango.dev/docs/api-integrations/[slug]
setup_guide_url: https://nango.dev/docs/api-integrations/[slug]/how-to-register-your-own-[slug]-oauth-app
For OAuth2 (with connectionConfig):
[slug]:
display_name: [Integration Name]
# ... other provider config ...
docs: https://nango.dev/docs/api-integrations/[slug]
setup_guide_url: https://nango.dev/docs/api-integrations/[slug]/how-to-register-your-own-[slug]-oauth-app
docs_connect: https://nango.dev/docs/api-integrations/[slug]/connect
For all non-OAuth2 auth modes:
[slug]:
display_name: [Integration Name]
# ... other provider config ...
docs: https://nango.dev/docs/api-integrations/[slug]
setup_guide_url: https://nango.dev/docs/api-integrations/[slug]/how-to-obtain-your-[slug]-api-key
docs_connect: https://nango.dev/docs/api-integrations/[slug]/connect
packages/providers/providers.yaml
auth_modecategories from the allowed listauthorization_url and token_url (if OAuth)proxy.base_url and headersproxy.verification (only for API_KEY, BASIC, JWT) - use simplest endpoint, set limit=1 if supportedconnection_config (if needed)credentials (if needed)docs URLsetup_guide_url (if OAuth)docs_connect (if needed)docs/api-integrations/[slug].mdxdocs/api-integrations/[slug]/how-to-register-your-own-[slug]-oauth-app.mdxdocs/api-integrations/[slug]/connect.mdx| Mistake | Fix |
|---|---|
| Not starting with providers.yaml | Always configure provider first - it contains all needed info |
| Adding provider in wrong order | Providers must be added in alphabetical order by slug in providers.yaml |
| Adding setup guide to docs.json | Only add main page; setup guide accessed via links |
| Wrong link format in guides section | Use /api-integrations/[slug]/how-to-register-your-own-[slug]-oauth-app |
| Missing two spaces after guide links | Add (two spaces) after closing ) for proper line breaks |
| Wrong slug format | Use lowercase with hyphens (e.g., google-calendar, not googleCalendar) |
| Not updating providers.yaml | Must add docs and setup_guide_url/docs_connect properties |
| Missing connect.mdx for non-OAuth2 | All non-OAuth2 auth modes require connect.mdx |
| Missing connect.mdx for OAuth2 with connectionConfig | OAuth2 with connectionConfig needs both setup guide AND connect.mdx |
| Wrong authorization_url format | Use ${connectionConfig.field} for dynamic values |
| Adding verification for OAuth auth modes | Only API_KEY, BASIC, and JWT need verification configuration |
| Using complex endpoints for verification | Use the simplest endpoint possible (e.g., /me, /user) |
| Not setting limit=1 for verification | If provider supports limit, set it to 1 to speed up connection creation |
how-to-register-your-own-[slug]-oauth-app.mdx)https://api.nango.dev/oauth/callbackconnect.mdx to show how to get connection config valuesconnect.mdx (not setup guide)connect.mdx (not setup guide)connect.mdx (not setup guide)https://api.nango.dev/oauth/callbackconnect.mdx (not setup guide)Files created:
packages/providers/providers.yaml - Provider configurationdocs/api-integrations/slab.mdx - Main page with quickstartdocs/api-integrations/slab/connect.mdx - Connect guidedocs.json entry:
"api-integrations/slab"
providers.yaml entry:
slab:
display_name: Slab
categories:
- productivity
- knowledge-base
auth_mode: API_KEY
proxy:
base_url: https://api.slab.com
headers:
authorization: Token ${apiKey}
content-type: application/json
verification:
method: POST
headers:
content-type: application/json
endpoints:
- /v1/graphql
docs: https://nango.dev/docs/api-integrations/slab
setup_guide_url: https://nango.dev/docs/api-integrations/slab/how-to-obtain-your-slab-api-key
docs_connect: https://nango.dev/docs/api-integrations/slab/connect
credentials:
apiKey:
type: string
title: API Token
description: Your Slab API token
secret: true
doc_section: '#step-1-generating-your-slab-api-token'