Creating Integration Documentation
Overview
Create and maintain Nango integration documentation following the established structure: main integration page with 4-step quickstart, separate setup guide, optional connect guide, and proper configuration in docs.json and providers.yaml.
When to Use
- Adding documentation for a brand new integration
- Creating docs for an integration that doesn't exist yet
- User asks to "add docs for [integration]" or "create documentation for [integration]"
- Editing an existing integration's main page, setup guide, or connect guide
When NOT to Use
- Migrating existing docs (use nango-docs-migrator agent instead)
- General documentation changes
Docs Conventions
docs/AGENTS.md is the source of truth for site-wide docs conventions and applies to every page this skill creates or edits. The rules that bite most often on integration pages:
- Start body headings at H2 — the frontmatter
titleis the page's only H1, soconnect.mdxand setup guides open at## Overview, never# Overview. - Sentence case for titles, sidebar titles, and headings.
- Run
mintlify broken-linksfromdocs/after any change to headings, page paths, or internal links, and confirmsuccess no broken links found.
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]-api-oauth-app.mdx |
OAuth app registration steps |
| Connect guide | docs/api-integrations/[slug]/connect.mdx |
Optional: custom connection UI |
| Syncs snippet | snippets/generated/[slug]/PreBuiltUseCases.mdx |
Auto-generated or empty state |
| Navigation | docs/docs.json |
Add to "APIs & Integrations" group |
| Provider config | packages/providers/providers.yaml |
Add docs and setup_guide_url |
Required Information
Before creating docs, gather:
- Integration name (e.g., "Slack", "Salesforce")
- Integration slug (e.g., "slack", "salesforce", "google-calendar")
- Auth type (OAuth2, API Key, Basic Auth)
- API base URL (for proxy examples)
- API documentation URL (official docs link)
- OAuth setup steps (if OAuth - how to get credentials)
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 [Environment API key](/reference/backend/http-api/api-keys), [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-API-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({ apiKey: '<NANGO-API-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/backend/backend-sdk/node#get-a-connection-with-credentials) or [API](/reference/backend/http-api/connections/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) to integrate Nango in your app.
To obtain your own 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] API OAuth app](/api-integrations/[slug]/how-to-register-your-own-[slug]-api-oauth-app)
Register an OAuth app with [Integration Name] and obtain credentials to connect it to Nango
Official docs: [[Integration Name] API docs]([API_DOCS_URL])
## 🧩 Pre-built syncs & tools for [Integration Name]
Enable them in your dashboard. [Extend and customize](/guides/platform/functions/functions-guide#extend-a-template) to fit your needs.
import PreBuiltUseCases from "/snippets/generated/[slug]/PreBuiltUseCases.mdx"
<PreBuiltUseCases />
---Nango-managed OAuth apps: Nango-managed OAuth apps are production-ready. Never describe them as "test" apps, "for testing only", or something to replace before going live, and don't call your own credentials "production credentials". Link to Nango-managed OAuth apps for the tradeoffs instead of restating them. ("Production credentials" is fine when the provider itself issues separate sandbox and production credentials, as athenahealth does.) Only say an API has a Nango-managed OAuth app if it appears in the list under APIs with a Nango-managed OAuth app. If it does, add the standard <Note> to the "Create the integration" step. Also change the "Implement Nango in your app" step's last line to "To use your own OAuth app instead of the Nango-managed one, follow the setup guide linked below." If it doesn't, say so and point to the setup guide.
Setup Guide
Path: docs/api-integrations/[slug]/how-to-register-your-own-[slug]-api-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]).
---Empty Syncs Snippet
Path: snippets/generated/[slug]/PreBuiltUseCases.mdx
_No pre-built syncs or tools available yet._
<Tip>Not seeing the integration you need? [Build your own](https://nango.dev/docs/guides/platform/functions/functions-guide) independently.</Tip>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 are accessed via links, not navigation
providers.yaml
Add or update the provider entry with docs URLs:
[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]-api-oauth-appIf connect guide exists, also add:
docs_connect: https://nango.dev/docs/api-integrations/[slug]/connectImplementation Checklist
- Gather integration info (name, slug, auth type, API URLs)
- Create main page at
docs/api-integrations/[slug].mdx - Create setup guide at
docs/api-integrations/[slug]/how-to-register-your-own-[slug]-api-oauth-app.mdx - Create empty syncs snippet at
snippets/generated/[slug]/PreBuiltUseCases.mdx - Add to docs.json "APIs & Integrations" group (alphabetically)
- Add docs URLs to providers.yaml entry
- Verify all links work
- Test MDX syntax is valid
Common Mistakes
| Mistake | Fix |
|---|---|
| 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]-api-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) |
| Forgetting PreBuiltUseCases snippet | Always create it, even if empty |
| Not updating providers.yaml | Must add docs and setup_guide_url properties |
Auth Type Variations
OAuth2 (most common)
- Use standard setup guide template
- Link to OAuth documentation
- Mention callback URL:
https://api.nango.dev/oauth/callback
API Key
- Modify setup guide title: "How to obtain your [Integration Name] API key"
- Focus on where to find/generate API keys
- No OAuth callback needed
Basic Auth
- Modify setup guide title: "How to configure [Integration Name] credentials"
- Document username/password or API key requirements
Example: Complete Slack Integration
Files created:
docs/api-integrations/slack.mdx- Main page with quickstartdocs/api-integrations/slack/how-to-register-your-own-slack-api-oauth-app.mdx- Setup guidesnippets/generated/slack/PreBuiltUseCases.mdx- Syncs snippet
docs.json entry:
"api-integrations/slack"providers.yaml entry:
slack:
docs: https://nango.dev/docs/api-integrations/slack
setup_guide_url: https://nango.dev/docs/api-integrations/slack/how-to-register-your-own-slack-api-oauth-app