Skip to main content

​
How API configurations work in Nango

Contributing a new API configuration means Nango users will be able to build integrations for this API. The only required part of the configuration is related to authentication. The rest is optional and optimizes the developer experience of building integrations for this API (e.g. Proxy default base URL, pagination helper, rate-limit helper). API configurations take the form of short YAML entries, living in a single file called providers.yaml. Most API configurations only need to make use of 2-3 configuration keys, but in some cases you might need more.

​
API configuration options

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

    # Proxy
    proxy:
        base_url: https://gitlab.example.com # Presets the base URL when using the Proxy (supports string interpolation, e.g. Salesforce).

    ##########
    # Optional fields
    ##########
    # Additional params
    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: https://api.example.com/oauth/refresh # 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
    redirect_uri_metadata:
        - subdomain # Save the 'subdomain' query parameter value returned in the Redirect URI (Connection Metadata)
    token_response_metadata:
        - scopes # Save the 'scopes' query parameter value returned in the token response (Connection Metadata)

    # Advanced
    token_expiration_buffer: 360 # In seconds. If omitted, tokens refresh if fetched within 15mins of expiration. This field overrides this buffer (e.g. for APIs with very-short-lived tokens).
API configurations support parameters using string interpolation 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-by-step guide to add an API configuration

​
Step 1: Add your new provider to providers.yaml

Fork the repo and edit the providers.yaml file as explained above to add support for the new API.

​
Step 2: Test your new provider

To test your new provider, go to the nango folder root and run: 
docker compose up
When you are ready to test your new API configuration: 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). Trigger the OAuth Flow Run an OAuth flow on the local Dashboard. You can modify the ports in the docker compose if there are any conflicts with other local services on your host machine. Check the access token in the dashboard If all goes well, you should see your new connection in the Connections tab 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>.mdx (e.g. github.md) corresponding to your new integration to the docs-v2/integrations/all folder. You can check out asana for an example. Also, add your new documentation page to docs-v2/mint.json in the Supported APIs group (in alphabetical order).

​
Step 4: Submit your PR

Submit your PR with the new provider to the Nango repo. Please thoroughly test the integration. Thanks a lot for your contribution!! ❤️

​
Need help?

Ask any question on the Slack community.
⌘I