​

Create a free Nango account

Sign up for a free Nango account (this feature is free & unlimited, no credit card needed):

​

Create an integration

Go to the Integrations tab, choose to configure a new integration, and choose an API to integrate with.

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

On the Nango integration page, click Connect to test the authorization. After authorizing API access for one of the modes described below, a connection 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

​

Integrate the frontend SDK

Once you have tested that the authorization flow works for your own external account, you can trigger authorization flows for your customers from your app with the Nango SDK.

Get your Public Key from the Environment Settings tab.

In your frontend, initiate Nango (reference):

import Nango from '@nangohq/frontend';

let nango = new Nango({ publicKey: '<PUBLIC-KEY>' });

Initiate the authorization flow (reference):

• OAuth
• API Key
• Basic Auth

nango
    .auth('<INTEGRATION-ID>', '<CONNECTION-ID>')
    .then((result) => {
        // Show success UI.
    })
    .catch((error) => {
        // Show failure UI.
    });

​

Listen for webhooks

Your backend is notified by Nango when an authorization attempt is completed, successful or not.

To set this up:

1. go to the Environment Settings tab
2. specify a Webhook URL to which Nango will send notifications
3. listen for webhooks in your backend at the specified route
4. enable the “Send New Connection Creation Webhooks” checkbox

Nango webhooks are post requests with the following JSON body:

{
    "type": "auth", 
    "connectionId": "<CONNECTION-ID>",
    "authMode": "OAUTH1|OAUTH2|OAUTH2_CC|BASIC|API_KEY|APP_STORE|CUSTOM|APP|NONE",
    "providerConfigKey": "<INTEGRATION-ID>",
    "provider": "<API-CONFIGURATION-ID>",
    "environment": "dev" | "prod",
    "success": true | false,
    "operation": "creation" | "override" | "unknown",
    "error": "<ERROR>"
}

For each successful authorization attempt, persist the connection ID & integration ID in your database. You will need them to retrieve the connection credentials later.

​

APIs requiring connection-specific configuration for authorization

Some APIs require connection-specific configuration (e.g. Zendesk, Shopify).

For example, Zendesk has the following authorization URL, where the subdomain is specific to a user’s Zendesk account:

https://<USER-SUBDOMAIN>.zendesk.com/oauth/authorizations/new

For these cases, you must provide this configuration when calling nango.auth() (reference):

nango.auth('zendesk', '<CONNECTION-ID>', {
    params: { subdomain: '<ZENDESK-SUBDOMAIN>' }
});

In some cases you might want to override the scopes provided by an integration at the connection level. For this case you can pass in the scopes to nango.auth:

nango.auth('zendesk', '<CONNECTION-ID>', {
    params: { oauth_scopes_override: 'custom-connection-scope' }
});

This connection configuration is stored in the connection. You can retrieve it with the SDK (reference), API (reference), and the Nango UI.

​

Troubleshoot authorization errors

If an authorization request fails, you can analyze the relevant log in the Activity 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 to change your callback URL.