Adding Nango Provider Support

Adding Provider Support

Overview

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.

When to Use

• Adding support for a brand new provider
• Creating provider configuration and docs for an integration that doesn't exist yet
• User asks to "add support for [provider]", "add [provider] integration", or "create documentation for [provider]"

When NOT to Use

• Migrating existing docs (use nango-docs-migrator agent instead)
• Editing existing integration docs
• General documentation changes

Quick Reference

Note: Pre-built syncs snippets are automatically generated by an automated script - you do not need to create them manually.

Implementation Order

IMPORTANT: Always start by editing packages/providers/providers.yaml first. This file contains all the authentication configuration and connection details needed for the integration.

Step 1: Configure Provider in providers.yaml

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.

Common Auth Modes

The following auth modes are supported:

1. API_KEY - API key authentication
2. BASIC - Basic HTTP authentication
3. OAUTH1 - OAuth 1.0 authentication
4. OAUTH2 - OAuth 2.0 authentication
5. OAUTH2_CC - OAuth 2.0 Client Credentials flow
6. JWT - JSON Web Token authentication
7. TWO_STEP - Two-step authentication (e.g., username/password then token)
8. SIGNATURE - Signature-based authentication

Examples by Auth Mode

API_KEY Example

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'

OAUTH2 Example (without connectionConfig)

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

OAUTH2 Example (with connectionConfig)

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

BASIC Example

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

OAUTH2_CC Example

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

OAUTH1 Example

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

TWO_STEP Example

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

JWT Example

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'

SIGNATURE Example

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

Categories

When adding a provider, you must specify one or more categories from the following allowed list:

• accounting
• analytics
• ats
• banking
• cms
• communication
• crm
• design
• dev-tools
• e-commerce
• erp
• gaming
• hr
• invoicing
• knowledge-base
• legal
• marketing
• mcp
• other
• payment
• popular
• productivity
• search
• social
• sports
• storage
• support
• surveys
• ticketing
• video

Important: Only use categories from this list. Do not create new categories.

Key Fields for providers.yaml

• display_name: Required - The display name of the provider
• categories: Required - Array of categories from the allowed list above
• auth_mode: Required - One of the auth modes listed above
• authorization_url: Required for OAUTH2, OAUTH1 - The OAuth authorization URL
• token_url: Required for OAUTH2, OAUTH2_CC, OAUTH1, TWO_STEP, APP - The token endpoint URL
• proxy.base_url: Required - The base URL for API requests
• proxy.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 page
• setup_guide_url: Required for OAUTH2 - Link to OAuth app registration guide
• docs_connect: Required for non-OAuth2 OR OAuth2 with connectionConfig - Link to connect.mdx guide

Verification Configuration Guidelines

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

1. Use the simplest endpoint possible - Choose the most basic endpoint that validates credentials (e.g., /me, /user, /profile, /account)
2. Set limit to 1 if supported - If the provider accepts a limit parameter, set it to 1 to reduce response size and speed up connection creation
3. Use GET method when possible - GET requests are typically simpler and faster than POST
4. Keep it minimal - The verification endpoint should only verify credentials, not fetch large amounts of data

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

Step 2: Documentation Requirements

Documentation Files by Auth Mode

Summary:

• All auth modes need the main page ([slug].mdx)
• OAuth2 and OAuth1 need the setup guide (how-to-register-your-own-[slug]-oauth-app.mdx)
• All non-OAuth2 auth modes need connect.mdx
• OAuth2 with connectionConfig needs both setup guide AND connect.mdx

Required Information

Before creating docs, gather:

1. Integration name (e.g., "Slack", "Salesforce")
2. Integration slug (e.g., "slack", "salesforce", "google-calendar")
3. Categories (one or more from the allowed list above - e.g., productivity, crm, popular)
4. Auth type (see auth modes above)
5. API base URL (for proxy examples)
6. API documentation URL (official docs link)
7. OAuth setup steps (if OAuth - how to get credentials)
8. Connection config values (if connectionConfig exists - what users need to provide)

File Templates

Main Integration Page

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.

---

OAuth Setup Guide (for OAUTH2 and OAUTH1)

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]).

---

Connect Guide (for all non-OAuth2, and OAuth2 with connectionConfig)

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.

Configuration Updates

docs.json

Add to the "APIs & Integrations" group in alphabetical order:

{
  "group": "APIs & Integrations",
  "pages": [
    // ... other integrations alphabetically
    "api-integrations/[slug]",
    // ... more integrations
  ]
}

Important:

• Add ONLY the main page path (not setup guide or connect guide)
• Keep alphabetical order within the group
• Setup guides, connect guides and main docs are accessed via links, not navigation

providers.yaml

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

Implementation Checklist

• Step 1: Configure provider in packages/providers/providers.yaml
  • Add provider entry in alphabetical order by slug (provider key)
  • Add provider entry with correct auth_mode
  • Add categories from the allowed list
  • Configure authorization_url and token_url (if OAuth)
  • Set up proxy.base_url and headers
  • Add proxy.verification (only for API_KEY, BASIC, JWT) - use simplest endpoint, set limit=1 if supported
  • Add connection_config (if needed)
  • Add credentials (if needed)
  • Add docs URL
  • Add setup_guide_url (if OAuth)
  • Add docs_connect (if needed)
• Step 2: Create documentation files
  • Create main page at docs/api-integrations/[slug].mdx
  • Create setup guide (if OAuth2/OAuth1) at docs/api-integrations/[slug]/how-to-register-your-own-[slug]-oauth-app.mdx
  • Create connect guide (if non-OAuth2 or OAuth2 with connectionConfig) at docs/api-integrations/[slug]/connect.mdx
  • Note: Pre-built syncs snippets are automatically generated - no manual creation needed
• Step 3: Update navigation
  • Add to docs.json "APIs & Integrations" group (alphabetically)
• Step 4: Verify
  • Verify all links work
  • Test MDX syntax is valid
  • Confirm providers.yaml syntax is correct

Common Mistakes

Auth Type Variations

OAuth2 (most common)

• Use standard setup guide template (how-to-register-your-own-[slug]-oauth-app.mdx)
• Link to OAuth documentation
• Mention callback URL: https://api.nango.dev/oauth/callback
• If connectionConfig exists: Also create connect.mdx to show how to get connection config values

API Key

• Create connect.mdx (not setup guide)
• Focus on where to find/generate API keys
• Use connect.mdx template style
• No OAuth callback needed

Basic Auth

• Create connect.mdx (not setup guide)
• Document username/password or API key requirements
• Use connect.mdx template style

OAuth2_CC (Client Credentials)

• Create connect.mdx (not setup guide)
• Document how to obtain client ID and secret
• Use connect.mdx template style

OAuth1

• Use standard setup guide template
• Link to OAuth documentation
• Mention callback URL: https://api.nango.dev/oauth/callback

TWO_STEP, JWT, SIGNATURE, APP

• Create connect.mdx (not setup guide)
• Document credential requirements
• Use connect.mdx template style
• For APP with connectionConfig, also create connect.mdx

Example: Complete Slab Integration (API_KEY)

Files created:

1. packages/providers/providers.yaml - Provider configuration
2. docs/api-integrations/slab.mdx - Main page with quickstart
3. docs/api-integrations/slab/connect.mdx - Connect guide
4. Pre-built syncs snippet is automatically generated by the system

docs.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'