Authorize in your app (default UI)
Guide to letting your users authorize an external API from your application.
Pre-requisite: complete the Configuration guide.
Authorization overview.
1. Generate a session token (backend)
In your backend, set up an API endpoint that your frontend will call before each authorization attempt to retrieve a session token from Nango.
Here’s an example of how your backend can retrieve a session token from Nango (API / Node SDK references):
Passing a list of integration IDs in allowed_integrations
will display a list of integrations that the end user can pick from:
Nango's default authorization UI.
Passing a single integration ID in allowed_integrations
will send the end user directly to this integration’s authorization flow:
Nango's default authorization UI.
2. Trigger the auth flow (frontend)
In your frontend, load the Nango frontend SDK, retrieve the session token from the backend, and trigger the authorization flow.
Option 1: Use the default UI (Nango Connect)
Nango’s default authorization UI comes with pre-built features:
- Displays the necessary input fields, validates their format & provides end-user instructions
- Authorizes a specific integration or can display a list of integrations to choose from
- Is fully whitelabel, without any Nango branding
Nango's default authorization UI.
Option 2: Use your custom UI
Refer to the Authorize in your app (custom UI) guide.
3. Listen for webhooks & save the Connection ID (backend)
The connection ID, a UUID generated by Nango, is required to manage the connection and access its credentials & data. So you need to persist this ID.
Upon successful authorization, Nango will send a webhook to your backend with the connection ID.
To set up this webhook:
- go to the Environment Settings tab in the Nango UI
- specify a Webhook URL where Nango should send notifications
- enable the Send New Connection Creation Webhooks option
- create the specified route in your backend to handle Nango webhooks
Successful authorization webhooks sent by Nango are POST
requests with the following JSON body:
For each successful authorization, persist the connectionId
value alongside its corresponding user or organization, designated by endUser.endUserId
and endUser.organizationId
.
4. Run the authorization flow
You can now test the authorization flow directly from your app and verify that a connection is created in the Nango UI Connections tab.
Troubleshoot authorization errors
If an authorization request fails, you can analyze the relevant log in the Logs tab of the Nango UI.
Re-authorize an existing connection
Details in this guide.
Next
You have successfully set up the authorization flow for your users. Next steps:
- View new connections & associated credentials in the Connections tab of the Nango UI
- Retrieve connection credentials with the API or Node SDK
- Sync data from APIs
- Perform actions with APIs
- Perform direct request to APIs
Questions, problems, feedback? Please reach out in the Slack community.
Was this page helpful?