Skip to main content

​
Custom Callback URL

You can change the callback URL of Nango if you want to personalize it (e.g. use your own 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 you are ready, change your Nango callback URL in the Project Settings page (cloud).
Before saving the custom callback URL in Nango, ensure that:
  • the callback URL redirects to https://api.nango.dev/oauth/callback (e.g. 308 redirect) and passes along all query parameters
  • your OAuth app, as registered with the external API provider, has the new callback URL whitelisted
If you are self-hosting Nango, follow the instructions here to change your callback URL.

​
Connection Configuration

Some APIs require additional parameters to run an OAuth flow or make API requests. Some examples:
  • Zendesk OAuth has the following authorization URL, where the subdomain is specific to a user’s Zendesk account: 
    https://<USER-SUBDOMAIN>.zendesk.com/oauth/authorizations/new
  • Qualtrics, Shopify, and Gorgias have the same per-customer subdomains as Zendesk
  • Salesforce uses a different API base URL per customer, e.g. https://mycustomer.api.salesforce.com
  • Zoho uses different API base URLs for different data centers. E.g. US customer’s data is at https://accounts.zoho.com and EU customer’s at https://accounts.zoho.eu

​
Setting Connection Configuration

For some APIs, Nango requires additional details from the end user to run an OAuth flow or make API requests. This is documented in two places: For instance, to specify the subdomain for Zendesk, pass in an additional configuration object to nango.auth(): 
nango.auth(
        'zendesk',
        '<CONNECTION-ID>',
        {
            params: {
                subdomain: '<ZENDESK-SUBDOMAIN>' 
            }
        });

​
Automatically retrieved Connection Configuration

Some Connection Configurations, such as the base URL for the Salesforce API, are automatically retrieved by Nango. This is noted on the API’s Nango docs page. Nango will automatically use this information for the Proxy, but if needed, you can also retrieve it (see next section).

​
Fetching Connection Configuration data

Nango stores all configuration data in the connection objects. You can retrieve it with the SDKs or REST API. 
{
    ...,
    "connectionConfiguration": {
        "subdomain": "myshop",
        "instance_url": "https://mygreatcorp.api.salesforce.com"
    },
    ...
}

​
Storing custom metadata per Connection

Nango lets you store arbitrary metadata on the Connection. This is useful for:
  • Storing custom field mappings per customer (e.g. map “name” from the external API to “firstname” in your data model)
  • Storing per-customer configuration (e.g. which filters for syncing objects, categories to skip etc.)
  • Any other per-connection data you want to have available in your sync scripts
This metadata is available to you in syncs & actions with getMetadata(): 
interface Metadata {
    owner: string;
    repo: string;
    branch: string;
}

export default async function fetchData(nango: NangoSync) {
    const { owner, repo, branch } = await nango.getMetadata<Metadata>();
    ...
}
It can also be set and retrieved with the SDKs and the REST API. Check these pages for the methods to set and retrieve it.

​
Connection-Specific Authorization Params

Some APIs require to pass additional query parameters in the authorization URL. If this applies to all users & use-cases, these params can be added to the providers.yaml API configurations. But sometimes, the additional authorization parameter is specific to a user or a use-case. In this case, it is possible to add it to the nango.auth() call from the Frontend SDK: 
nango.auth('discord', '<CONNECTION-ID>', { authorization_params: { key: 'value' } });

​
Securing the Frontend SDK calls with HMAC

By default, this feature is disabled and your frontend can attempt to create a new connection using any Integration ID and Connection ID. But you might want to ensure that the app user is the only one that can create a new connection with that Connection ID. To enable this feature:
  1. Add a secret HMAC key in your Project Settings. Pick a large, random value!
  2. Generate the HMAC signature in your backend and pass it to your frontend where you make the nango.auth calls.
  3. When ready, enable the HMAC check in the Project settings. Nango will now reject auth calls without or mismatching HMAC signature, so make sure your code is ready before you flip the switch!
The HMAC digest is generated by your backend using the secret HMAC key you set and the combination of the Integration ID and the Connection ID. Your backend should keep the secret HMAC key private and not reveal it to your frontend or end-users! In your frontend, pass the HMAC digest as follows in nango.auth: 
nango.auth('<INTEGRATION-ID>', '<CONNECTION-ID>', { hmac: '<HMAC-DIGEST>' });
The HMAC digest can be generated by using the following code in your backend (node example): 
import * as crypto from 'node:crypto';

// TODO: execute authentication and authorization checks before generating the HMAC digest.

// The value of '<HMAC-KEY>' should match the secret HMAC key set in your project settings.
const hmac = crypto.createHmac('sha256', '<HMAC-KEY>');
hmac.update('<INTEGRATION-ID>:<CONNECTION-ID>');
const digest = hmac.digest('hex');

// TODO: return the value of `digest` to the frontend to pass to `nango.auth`.

​
Configure Integrations Programmatically

Nango offers a REST API to programmatically manage your integrations.

​
Questions, problems, feedback?

We are happy to help! Please reach out on the Slack community, we are very active there.
⌘I