Authorize an API

Step-by-step guide on how to getting user authorization to access an external API on their behalf.

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.

Each API has a dedicated Nango documentation page with useful links, gotchas, etc.

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

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).

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

For OAuth, the nango.auth() method will trigger the OAuth flow in a popup, to let the user log in to their external account.

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

Nango will automatically collect, store, and refresh the API credentials as needed.

Before using Nango in production, we advise securing the frontend SDK (cf. next section).

Secure the frontend SDK

Before moving to production, you must ensure nobody else can create a new connection:

Add a secret HMAC key in your Environment Settings tab. Pick a large, random value.

Generate the HMAC signature in your backend and pass it to your frontend before you make nango.auth calls. The HMAC digest can be generated with the following code (node example):

import * as crypto from 'node:crypto';

// Enforce backend authentication before generating the HMAC digest.

// The value of '<HMAC-KEY>' should match the secret HMAC key set in your environment 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`.

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 (reference):

nango.auth('<INTEGRATION-ID>', '<CONNECTION-ID>', { hmac: '<HMAC-DIGEST>' });

Enable the HMAC checkbox in the Environment Settings tab.

Nango will reject auth calls without a proper HMAC signature, so make sure your code is ready before you flip the switch!

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>' }
});

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.

Questions, problems, feedback? Please reach out in the Slack community.