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

# 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

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

## 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

```yaml
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)

```yaml
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)

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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:**

```yaml
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

| 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:**
- **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`

```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`

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

```mdx
---
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):**

```mdx
---
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:

```json
{
  "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):**
```yaml
[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):**
```yaml
[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:**
```yaml
[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

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

## 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:**
```json
"api-integrations/slab"
```

**providers.yaml entry:**
```yaml
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'
```

---