Skip to main content

Contribute a New Provider

Adding support for a new provider to Nango is fast & easy. Please follow the steps below and we will be happy to accept your PR!

If you find a bug with one of the existing providers feel free to use these steps to submit a PR with a fix. Thank you!

Step 0: A quick overview of how provider templates work in Nango

Support for the OAuth flow of different providers in Nango is implemented with templates: A small config that tells Nango how to perform the OAuth flow for the specific provider.

All templates of Nango live in a single file called providers.yaml in the server package. More about YAML here.

Most templates only need to make use of 2-3 configuration keys, but in some cases you might need more. For a full list of configuration options please check the type definitions here.

The most commonly used configuration options are:

provider-slug: # Shorthand for the provider, ideally the provider's name. Must be unique. Kebab case.
# Mandatory fields
auth_mode: OAUTH2 # Either OAUTH1 (for OAuth 1.0a) or OAUTH2
authorization_url: https://${connectionConfig.params.subdomain} # The URL of the authorization page for the OAuth service (supports string interpolation)
token_url: https://${connectionConfig.params.subdomain} # The URL for the token request (supports string interpolation)

# Optional fields
authorization_params: # Additional parameters to pass along in the authorization step
response_type: code
token_params: # Additional parameters to pass along in the token request
mycoolparam: value
refresh_url: # The URL to use for refreshing the access token (only if different from token_url)
scope_separator: ',' # String to use to separate scopes. Defaults to ' ' (1 space) if not provided

# Metadata capture
- subdomain # Save the 'subdomain' query parameter value returned in the Redirect URI (Connection Metadata)
- scopes # Save the 'scopes' query parameter value returned in the token response (Connection Metadata)

Templates support parameters using string interpolation (cf. flow Configuration) for dynamic URLs, etc.


You can configure some Connection Metadata, which is additional metadata that you want to capture during the OAuth flow and store in the Connection.

Step 1: Add your new provider to providers.yaml

Fork the repo and edit the packages/server/providers.yaml file as explained above to add support for the new provider. The API documentation should contain all the details you need on the OAuth flow to complete this step.

We are here if you need help with this.

Step 2: Test your new provider


Some OAuth providers are very restrictive with callback URIs and require https or don't allow localhost as a domain/URL. This can make it very hard to test things locally.

The easiest workaround we found is to use this simple service:

With this the Nango localhost callback URL becomes and you will need to update the NANGO_CALLBACK_URL in the .env file:


To test your new provider:

The docker compose configuration in the root of the repo docker-compose.yaml will run 3 containers.

  1. Postgres DB
  2. Nango Server
  3. Test Website to Trigger the OAuth Flow

To propagate your changes after editing the providers.yaml file, run:

docker compose restart nango-server # Force a restart, which will load in the yaml again
docker compose run nango-server cat packages/server/providers.yaml # print the contents of the providers file from inside the container

When you are ready to test your new provider template:

1. Add your client credentials to the local Nango Server

Open the local dashboard in your browser and add a new Integration with your freshly added provider (it should show up in the provider dropdown).

2. Navigate to the Test Website and Trigger the OAuth Flow

The test site should be running at http://localhost:8001/bin/quickstart.html

You can modify the ports in the docker compose if there are any conflicts with other local services on your host machine.

3. Check the access token in the dashboard

If all goes well you should see your new Connection in the Connections list in the dashboard.

Check the Connection details and make sure all looks as expected (access token, refresh token, metadata).

Step 3: Add your integration to the Documentation

Add a file named <provider_slug>.md (e.g. corresponding to your new integration to the docs/docs/providers folder. You can check out check out airtable for an example.

Also, add your new documentation page to docs/sidebar.js in the items array (in alphabetical order):

[Provider Sidebar List]

Step 4: Add the integration logo (optional)

To be displayed in the app and docs, optionally add the provider logo in SVG to packages/webapp/public/images/template-logos/. The name of the file should be <provider_slug>.svg. Ideally, the logo should be 44px on its longest side (width or height), inside a 62x62px transparent box.

Step 5: Submit your PR

Submit your PR with the new provider to the Nango repo. Please thoroughly test the integration and include the following mention in your PR: "I successfully tested the provider config creation, OAuth flow & valid token."

We will review your PR asap and merge it into the main Nango repo for inclusion with the next release.

Thanks a lot for your contribution!! ❤️

Where to get help

If you get stuck or need help please join our Slack community where the Nango contributors hang out. We will do our best to help you and get Nango to work with the OAuth flow of your provider.