Merge branch 'alan/nan-2168/missing-fields-backfill' into alan/nan-21…

…68-surface-integrationsconnections-errors-in-nango-ui/integration-validation-show-ui

CONTRIBUTING.md

@@ -6,7 +6,7 @@ For contributions, please [submit an issue](https://github.com/NangoHQ/nango/iss
 
 # Contributing
 
-You can run Nango locally with Docker ([step-by-step guide](https://docs.nango.dev/host/self-host/local)) and contribute an API ([step-by-step guide](https://docs.nango.dev/customize/guides/contribute-an-api)).
+You can run Nango locally with Docker ([step-by-step guide](https://docs.nango.dev/host/self-host/local)) and contribute an API ([step-by-step guide](https://docs.nango.dev/guides/customize/contribute-an-api)).
 
 ## Develop locally
 

README.md

@@ -20,7 +20,7 @@ Ship integrations fast. Maintain full control.
     ·
     <a href="https://nango.dev">Website</a>
     ·
-    <a href="https://docs.nango.dev/customize/guides/contribute-an-api">Contribute an API</a>
+    <a href="https://docs.nango.dev/guides/customize/contribute-an-api">Contribute an API</a>
     ·
     <a href="https://nango.dev/slack">Slack Community</a>
 </p>
@@ -89,9 +89,9 @@ Sign up for free:
 
 Our mission is to enable all SaaS to seamlessly integrate together. By being open source, every engineer can contribute improvements to the platform for everyone:
 
-- [Contribute an API](https://docs.nango.dev/customize/guides/contribute-an-api)
-- [Create a custom integration](https://docs.nango.dev/customize/guides/create-a-custom-integration)
-- [Extend an integration template](https://docs.nango.dev/customize/guides/extend-an-integration-template)
+- [Contribute an API](https://docs.nango.dev/guides/customize/contribute-an-api)
+- [Create a custom integration](https://docs.nango.dev/guides/customize/create-a-custom-integration)
+- [Extend an integration template](https://docs.nango.dev/guides/customize/extend-an-integration-template)
 
 # 📚 Learn more
 

docs-v2/integrate/guides/advanced/authorize-an-api-headless.mdx → docs-v2/guides/authorize-an-api-from-your-app-with-custom-ui.mdx

@@ -1,14 +1,10 @@
 ---
-title: 'Authorize an API (headless)'
-sidebarTitle: 'Authorize an API (headless)'
-description: 'Step-by-step guide on how to getting user authorization to access an external API on their behalf.'
+title: 'Authorize an API from you app (custom UI)'
+sidebarTitle: 'Authorize an API from you app (custom UI)'
+description: 'Step-by-step guide on getting user authorization with your own UI.'
 ---
 
-# Authorize users from your app using headless frontend
-
-<Tip>
-It's recommended to use <a href="/integrate/guides/authorize-an-api">Nango Connect</a>, but you can build your own UI using the following API
-</Tip>
+# Authorize users from your app using your own UI
 
 ## Integrate the frontend SDK
 
@@ -93,10 +89,6 @@ nango
 Nango will automatically collect, store, and refresh the API credentials as needed.
 </Tip>
 
-<Info>
-Before using Nango in production, we advise [securing the frontend SDK](/integrate/guides/advanced/secure-frontend-sdk).
-</Info>
-
 ## APIs requiring connection-specific configuration for authorization
 
 Some APIs require connection-specific configuration (e.g. Zendesk, Shopify).
@@ -127,16 +119,6 @@ This _connection configuration_ is stored in the connection. You can retrieve it
 
 If an authorization request fails, you can analyze the relevant log in the _Logs_ tab of the Nango UI.
 
-# Use a custom callback URL
-
-You can personalize Nango's callback URL (e.g. use your domain). If you are using Nango Cloud, follow these steps:
-
-1. Add a new endpoint in your app, e.g. `https://EXAMPLE.com/oauth-callback`. All requests to this endpoint should redirect to `https://api.nango.dev/oauth/callback` and **pass along all original parameters**. The easiest way to do this is with a 308 redirect.
-2. Change the registered OAuth callback URL with all API providers. Otherwise, they will refuse new flows!
-3. When ready, change your Nango callback URL in the _Environment Settings_ tab.
-
-If you are self-hosting Nango, follow the instructions [here](/host/self-host/self-hosting-instructions) to change your callback URL.
-
 <Tip>
 **Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
 </Tip>

docs-v2/customize/guides/create-a-custom-integration.mdx → docs-v2/guides/customize/create-a-custom-integration.mdx

@@ -7,7 +7,7 @@ description: 'Step-by-step guide on how to create a custom integration with Nang
 In Nango, integration use-cases are mapped to [syncs](/understand/concepts/syncs) and [actions](/understand/concepts/actions). Before starting, determine if a sync, an action, or a combination of both fits your use case.
 
 <Info>
-Pre-requisite: set up an integrations folder ([step-by-step guide](/customize/guides/setup)).
+Pre-requisite: completion of the [_Set up the CLI and folder_ guide](/guides/customize/setup).
 </Info>
 
 # Edit the `nango.yaml` configuration

docs-v2/customize/guides/extend-an-integration-template.mdx → docs-v2/guides/customize/extend-an-integration-template.mdx

@@ -11,7 +11,7 @@ Here is the [list of publicly available integration templates](/integrations/ove
 You can activate template integrations directly in the Nango UI to get started fast. But if you want to edit their code or configuration, you must pull them in your [integrations folder](/understand/concepts/scripts#integration-folder) as described below.
 
 <Info>
-Pre-requisite: set up an integrations folder ([step-by-step guide](/customize/guides/setup)).
+Pre-requisite: set up an integrations folder ([step-by-step guide](/guides/customize/setup)).
 </Info>
 
 # Download the template code
@@ -28,7 +28,7 @@ There is no need to copy/paste the `models.ts` file from the template folder; it
 
 # Customize the template at will
 
-Edit the `nango.yaml` configuration and integration scripts as you see fit ([step-by-step guide](/customize/guides/create-a-custom-integration)).
+Edit the `nango.yaml` configuration and integration scripts as you see fit ([step-by-step guide](/guides/customize/create-a-custom-integration)).
 
 <Warning>
 If a custom integration script name conflicts with a template name, the custom integration script will override the template in the Nango UI.

docs-v2/customize/guides/advanced/handle-large-datasets.mdx → docs-v2/guides/customize/handle-large-datasets.mdx

@@ -14,7 +14,7 @@ When syncing data in Nango, there are actually two syncing processes happening:
 - Nango syncing with the external system, managed by [integration scripts](/understand/concepts/scripts)
 - Your app syncing with Nango, managed by your app's code using the Nango API
 
-Your app syncs with Nango in the same way regardless of the volume of the dataset ([guide](/integrate/guides/sync-data-from-an-api)). Nango maintains a cache of the synced data, and the Nango API allows you to fetch only the incremental changes for your convenience.
+Your app syncs with Nango in the same way regardless of the volume of the dataset ([guide](/guides/getting-started/read-from-an-api)). Nango maintains a cache of the synced data, and the Nango API allows you to fetch only the incremental changes for your convenience.
 
 Below, we explore various approaches on how to sync data from the external system to Nango, even for large datasets.
 

docs-v2/integrate/guides/authorize-an-api.mdx → docs-v2/guides/getting-started/authorize-an-api-from-your-app.mdx

@@ -1,63 +1,12 @@
 ---
-title: 'Authorize an API'
-sidebarTitle: 'Authorize an API'
-description: 'Step-by-step guide on how to getting user authorization to access an external API on their behalf.'
+title: 'Authorize users from your app'
+sidebarTitle: 'Authorize users from your app'
+description: 'Step-by-step guide on getting user authorization to access an external API, from your application.'
 ---
 
-# Create a free Nango account
-
-Sign up for a free Nango account (**this feature is free & unlimited**, no credit card needed):
-[![Try Nango Cloud](/images/nango-deploy-button.svg)](https://app.nango.dev/signup)
-
-# Create an integration
-
-Go to the _Integrations_ tab, choose to configure a new [integration](/understand/concepts/integrations), and choose an API to integrate with.
-
-<Tip>
-    Each API has a dedicated Nango documentation page with useful links, gotchas, etc.
-</Tip>
-
-APIs have different ways to authorize requests: OAuth, API key, Basic, custom. Nango abstracts away the difficulties of working with each one.
-
-**For OAuth**
-
-OAuth APIs require you to register your OAuth application on their developer portal.
-
-When registering, the API provider will prompt you for the `Callback URL`. Use the one displayed in the Nango integration settings. Remember to register the required scopes in the Nango integration settings and, if necessary, with the API provider.
-
-Collect your OAuth app's `Client ID` and `Client Secret` from the API portal and input them in your Nango integration settings.
-
-**For API Key & Basic**
-
-No configuration is necessary for APIs supporting API key & Basic authorization.
-
-**For Custom Authorization**
-
-APIs like Stripe & GitHub Apps have custom authorization. Configurations vary and are described in the Nango integration settings.
-
-# Test the authorization
-
-<Tip>
-Your can test the authorization flow directly in the Nango UI, using your own external account credentials.
-
-In production, the authorization flow will be triggered from your app, promping each of your customers' to enter their external account credentials (cf. next section).
-</Tip>
-
-On the Nango integration page, click `Add Connection` to test the authorization. After authorizing API access for one of the modes described below, a [connection](/understand/concepts/connections) should be successfully created in the _Connections_ tab.
-
-**For OAuth**
-
-Input your external account credentials in the popup dialog to test the authorization.
-
-**For API Key & Basic**
-
-Input the API key (or username/password for Basic) to test the authorization.
-
-**For Custom Authorization**
-
-The authorization flow will vary based on the API, but you will most likely have to log in to your external account via a popup dialog.
-
-# Authorize users from your app
+<Info>
+Pre-requisite: completion of the [_Configure an integration_ guide](/guides/getting-started/configure-an-integration).
+</Info>
 
 Nango Connect requires a unique temporary token to securely authenticate your users.
 
@@ -186,15 +135,15 @@ Nango webhooks are post requests with the following JSON body:
 For each successful authorization attempt, persist the connection ID & integration ID in your database. You will need them to retrieve the connection credentials later.
 
 <Info>
-Before using Nango in production, we advise [verifying webhook signatures](/integrate/guides/advanced/verify-webhooks-from-nango).
+Before using Nango in production, we advise [verifying webhook signatures](/guides/verify-webhooks-from-nango).
 </Info>
 
 # You are ready
 
 Your users can now launch Nango Connect and connect to any of your integrations, Nango is taking care of the rest.
 
 
-<Card title="Want to build your own UI?" icon="code" href="/integrate/guides/advanced/authorize-an-api-headless" horizontal>
+<Card title="Want to build your own UI?" icon="code" href="/guides/authorize-an-api-from-your-app-with-custom-ui" horizontal>
   Use the Headless API to create your custom experience
 </Card>
 

docs-v2/guides/getting-started/configure-an-integration.mdx

@@ -0,0 +1,40 @@
+---
+title: 'Configure an integration'
+sidebarTitle: 'Configure an integration'
+description: 'Step-by-step guide to configure an integration in Nango.'
+---
+
+# Create an account
+
+Sign up for a Nango account (free):
+[![Try Nango Cloud](/images/nango-deploy-button.svg)](https://app.nango.dev/signup)
+
+# Create an integration
+
+Go to [Integrations](https://app.nango.dev/dev/integrations), click the  _Configure New Integration_ button and select the API to integrate with.
+
+<Tip>
+    Each API has a dedicated Nango documentation page with useful links, gotchas, etc.
+</Tip>
+
+APIs have different ways to authorize requests: OAuth, API key, Basic, custom. Nango abstracts away the difficulties of working with each one.
+
+<Accordion title="Only for OAuth APIs">
+    OAuth APIs require you to register your OAuth application on their developer portal.
+
+    When registering, the API provider will prompt you for the `Callback URL`. Use the one displayed in the Nango integration settings. Remember to register the required scopes in the Nango integration settings and, if necessary, with the API provider.
+
+    Collect your OAuth app's `Client ID` and `Client Secret` from the API portal and input them in your Nango integration settings.
+</Accordion>
+
+# Test the authorization
+
+If you don't have one already, create a test account for the external API you want to integrate with.
+
+On the Nango integration page, click "Add Connection" to test the authorization. Enter your test account credentials to authorize the API.
+
+Once authorized, go to [Connections](https://app.nango.dev/dev/connections) to see the newly created connection. The "Authorization" tab contains the credentials necessary to consume the external API. These credentials are securelly stored and automatically refreshed.
+
+<Tip>
+**Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
+</Tip>

docs-v2/integrate/guides/sync-data-from-an-api.mdx → docs-v2/guides/getting-started/read-from-an-api.mdx

@@ -1,11 +1,11 @@
 ---
-title: 'Sync data from an API'
-sidebarTitle: 'Sync data from an API'
+title: 'Read from an API'
+sidebarTitle: 'Read from an API'
 description: 'Step-by-step guide on how to continuously sync data from an API (using a sync template).'
 ---
 
 <Info>
-Pre-requisite: creation of an integration and at least one connection ([step-by-step guide](/integrate/guides/authorize-an-api)).
+Pre-requisite: completion of the [_Configure an integration_ guide](/guides/getting-started/configure-an-integration).
 </Info>
 
 # Activate a sync template
@@ -19,7 +19,7 @@ Nango will automatically sync the corresponding [records](/understand/concepts/s
 <Tip>
 Is there no template for your API? Or none matching your exact use case?
 
-Learn more about how to [build a custom integration](/customize/guides/create-a-custom-integration), [extend a template](/customize/guides/extend-an-integration-template) or [request custom integrations from Nango experts](/host/managed-integrations).
+Learn more about how to [build a custom integration](/guides/customize/create-a-custom-integration) and [extend a template](/guides/customize/extend-an-integration-template).
 </Tip>
 
 # Listen for webhooks from Nango
@@ -46,7 +46,7 @@ Webhooks with non-2xx responses are retried with exponential backoff.
 </Tip>
 
 <Warning>
-Before using webhooks in production, verify their origin ([step-by-step guide](/integrate/guides/advanced/verify-webhooks-from-nango)).
+Before using webhooks in production, verify their origin ([step-by-step guide](/guides/verify-webhooks-from-nango)).
 </Warning>
 
 # Fetch the latest data
@@ -170,7 +170,7 @@ So, the overall logic for cursor-based synchronization should be:
 
 # Write back to APIs (2-way syncing)
 
-Write back to APIs with actions ([step-by-step guide](/integrate/guides/perform-workflows-with-an-api)) or proxy requests ([step-by-step guide](/integrate/guides/proxy-requests-to-an-api)).
+Write back to APIs with actions ([step-by-step guide](/guides/getting-started/write-to-an-api)) or proxy requests ([step-by-step guide](/guides/proxy-requests-to-an-api)).
 
 # Troubleshoot errors & monitor
 

docs-v2/integrate/guides/perform-workflows-with-an-api.mdx → docs-v2/guides/getting-started/write-to-an-api.mdx

@@ -1,11 +1,11 @@
 ---
-title: 'Perform workflows with an API'
-sidebarTitle: 'Perform workflows with an API'
-description: 'Step-by-step guide on how to perform workflows with an API (using an action template).'
+title: 'Write to an API'
+sidebarTitle: 'Write to an API'
+description: 'Step-by-step guide on how to write to an API (using an action template).'
 ---
 
 <Info>
-Pre-requisite: creation of an integration and at least one connection ([step-by-step guide](/integrate/guides/authorize-an-api)).
+Pre-requisite: completion of the [_Configure an integration_ guide](/guides/getting-started/configure-an-integration).
 </Info>
 
 # Activate an action template
@@ -17,7 +17,7 @@ Select your integration in the _Integrations_ tab, and navigate to the _Endpoint
 <Tip>
 Is there no template for your API? Or none matching your exact use case?
 
-Learn more about how to [build a custom integration](/customize/guides/create-a-custom-integration), [extend a template](/customize/guides/extend-an-integration-template) or [request custom integrations from Nango experts](/host/managed-integrations).
+Learn more about how to [build a custom integration](/guides/customize/create-a-custom-integration) and [extend a template](/guides/customize/extend-an-integration-template).
 </Tip>
 
 # Trigger an action

docs-v2/features/otlp-export.mdx → docs-v2/guides/otlp-export.mdx

@@ -1,5 +1,5 @@
 ---
-title: 'OpenTelemetry export'
+title: 'Export OpenTelemetry traces'
 ---
 
 ### Overview

docs-v2/integrate/guides/proxy-requests-to-an-api.mdx → docs-v2/guides/proxy-requests-to-an-api.mdx

@@ -5,7 +5,7 @@ description: 'Step-by-step guide on how to proxy requests to an API (using the _
 ---
 
 <Info>
-Pre-requisite: creation of an integration and at least one connection ([step-by-step guide](/integrate/guides/authorize-an-api)).
+Pre-requisite: completion of the [_Configure an integration_ guide](/guides/getting-started/configure-an-integration).
 </Info>
 
 The [Proxy](/understand/concepts/proxy) lets you query external APIs easily with credentials injection, request logging, and pre-configurations for base URLs, rate-limits, retries, etc.

docs-v2/integrate/guides/advanced/use-custom-field-mappings.mdx → docs-v2/guides/use-custom-field-mappings.mdx

@@ -9,7 +9,7 @@ Field mappings are necessary when a [sync](/understand/concepts/syncs) needs to
 # Prompt your customers for field mappings
 
 In your app:
-- fetch the list of custom fields available from the external API using an action ([step-by-step guide](/integrate/guides/perform-workflows-with-an-api))
+- fetch the list of custom fields available from the external API using an action ([step-by-step guide](/guides/getting-started/write-to-an-api))
 - display the full list of external custom fields to the user
 - prompt the user to associate the data you need to collect to the relevant external custom fields