This guide shows how to perform authenticated API requests through Nango.

This feature is free & unlimited on Nango Cloud.

​
When to use the Proxy

The Proxy makes it faster for you to query external APIs by handling:

  • Credential-injection in requests
  • Automatically sets the correct base URL
  • Logging & monitoring
  • Rate-limit handling (with automatic & configurable retries)

It is especially useful for:

  • One-off requests to fetch e.g. metadata from the API
  • Writing data back to the API on demand

If you want to continuously sync data from the external API, check out syncs. If you find yourself to many Proxy requests for a single workflow, checkout actions.

​
Using the Proxy

Before you can use Proxy requests you need to setup auth by following the Authorize APIs guide.

​
Proxy requests

  • Backend Node SDK

  • REST API

The backend Node SDK supports the Proxy and offers convenience functions such as nango.get({}), nango.post({}) etc.

Refer to the SDK Reference for full details on proxy options.

try {
    const res = await nango.proxy({
        method: 'POST',
        endpoint: '/calendar/v3/users/me/calendarList',
        providerConfigKey: '<INTEGRATION-ID>',
        connectionId: '<CONNECTION-ID>',
        retries: 5, // Retries with exponential backoff (optional, default 0)
        data: {
            id: 1,
            colorId: 'blue',
            selected: true
        }
    });

    // Response was 200!
    // See https://axios-http.com/docs/res_schema
    console.log(res.data);
} catch (error) {
    // Status of response != 200
    // See https://axios-http.com/docs/handling_errors
    console.log(error.response.data);
    console.log(error.response.status);
    console.log(error.response.headers);
}

Some APIs are not yet fully-configured to work with the Proxy and require you to indicate the base URL.

You can check if your API contains the proxy.base_url field in the providers.yaml configuration file.

If not, you need to add a baseUrlOverride field in your call to the Proxy as follow:

const res = await nango.proxy({
...
baseUrlOverride: 'https://gmail.googleapis.com',
...
});

Feel free to contribuge the proxy.base_url field to any API in the providers.yaml public file, or reach out on the Slack community to ask us to do it.

​
Proxy request logging

All requests that run through the Proxy are automatically logged to the Activity tab in the Nango Dashboard. The logs there can help you debug failing requests.

Proxy in Activity Tab

​
Need help?

Ask any question on the Slack community.

ActionsWebhooks