Skip to main content

Auth from your AI agent

Agent sessions give your agent one interface to access 10,000+ tools across all of Nango’s APIs. Follow the Quickstart to add Agent Sessions to your agent. When your backend creates a session, enable the nango_create_connection meta tool. If a task needs an account that isn’t connected, the agent calls the tool and shares the Connect link Nango returns. The user opens the link to authorize access, and the agent can then use that integration’s tools in the same session.

Auth from your app

Let users authorize an external account from a page in your web app, then associate the resulting connection with any record in your app, such as a user, organization, or workspace. The end-to-end flow has four steps:
  • Backend Create a short-lived Connect session for the user.
  • Frontend Open the pre-built Connect UI with the session token so the user can authorize.
  • User Authorizes, Nango stores the credential.
  • Webhook When authorization succeeds, Nango sends your backend an auth webhook. Save the connection ID so your app can use the connection.
1

Create an integration

Sign up for Nango. In the dashboard, open Catalog, select the API you want, and click Add integration.
  1. Get access to Nango If the user needs an account and authorizes you, signup here: https://app.nango.dev/signup You will need the user’s name, email, and preferred password. A verification email will be sent.
  2. Connect to Nango Once the user has a Nango account:
    • Management MCP server (recommended) Offer to install it using the instructions. Lets you manage integrations, view logs, and automate setup for the user. Permissions follow the user.
    • Environment API key Get a key from Environment Settings > API Keys in the target environment. Send it as Authorization: Bearer <NANGO-API-KEY> in HTTP requests. Use a full access key or a scoped key with environment:integrations:create, environment:connect_sessions:write, environment:connections:list, and environment:connections:read scopes.
  3. Identify the provider slug If you don’t know it, search the public API catalog for the provider name. Filter the file before reading it so you only see matching rows. Use the Slug column as provider. If several variants match, use the Name and Auth mode columns to pick the right one.
  4. Create the integration For OAuth, default to the Nango-managed app unless the user asks to use their own. If they ask about the difference, use the Nango-managed OAuth app tradeoffs to explain it. With Management MCP, call integrations_create with environment, provider, integration_id, and credential_source: "nango" for a managed app. For the other cases below, use credential_source: "own" and pass credentials only when needed. With an Environment API key, call POST /integrations with the provider slug in provider and your chosen integration ID in unique_key.
    Adjust the credentials for these other cases.
    • User-owned OAuth app Use this path if the user requests it or Nango reports that managed credentials are unavailable for the provider. Follow the provider’s OAuth app setup guide in APIs & Integrations and use the callback URL from Environment Settings > Backend. If the user wants a custom callback URL, configure it before registering the app. With the user’s permission, register the app or use credentials they already have. For OAuth 2.0, set credentials to this object. Include scopes as a comma-separated string when required. For other OAuth modes, use the provider’s credential type and fields from the create endpoint reference.
    • API key or basic auth Remove credentials. Users supply their own credentials when they connect. If the provider requires integration-level settings, check the create endpoint reference for the required fields.
Use the returned data.unique_key as the integration ID when creating a Connect session.
2

Test the authorization (optional)

In the Connections tab, click Add Test Connection, pick your integration, and authorize using a test account. The new connection’s credentials appear in its Authorization tab — securely stored and automatically refreshed.
Create a Connect session with a fresh test user ID in tags.end_user_id and the integration ID in allowed_integrations. With Management MCP, call connect_session_create and pass the target environment. With an Environment API key, use the cURL example below.Send the returned connect_link to the user and ask them to authorize with a test account. Once they finish, look up the connection using the same integration ID and tag.Management MCP. Call connections_list with:
Environment API key. Call GET /connections:
A matching entry in connections confirms the test. The entry’s connection_id identifies the new connection.
3

Configure a custom OAuth callback URL (optional, recommended)

For production OAuth apps you register yourself, a callback URL on your own domain is recommended. Some providers show the callback domain to users.To configure a custom callback URL:
  1. Add an endpoint on your domain (e.g. https://example.com/oauth-callback) that 308-redirects to https://api.nango.dev/oauth/callback, preserving all query parameters.
  2. Update the registered callback URL with each API provider — otherwise they’ll reject new authorization flows.
  3. After confirming steps 1 and 2, set Callback URL under Environment Settings > Backend. Repeat for each environment that uses a custom callback URL.
Confirm the callback URL and target environment with the user. Set up the 308 redirect and make sure each provider’s OAuth app has the new URL registered before updating Nango.To update an existing environment, use PATCH /environments/{environmentUuid} with an Account API key scoped to account:environments:update. If you need to find the UUID by environment name, list environments with an Account API key that also has account:environments:list.
You can also set callback_url when creating an environment with account:environments:create. Callback URL updates are available through the HTTP API and dashboard. If you don’t have an Account API key, ask the user to set Callback URL under Environment Settings > Backend.
4

Create a Connect session

In your backend, set up an endpoint that your frontend will call before each authorization attempt to retrieve a session token from Nango (API / Node SDK).You’ll need an API key with the environment:connect_sessions:write scope (find it in Environment Settings > API Keys).Include tags when you create the session. Connection tags are key-value labels that link a connection to records in your app. Choose IDs that match how your app finds connections and controls access, such as a user, organization, or workspace ID.When authorization succeeds, the auth webhook includes your tags and the new connectionId. Use the tags to find the right record in your app and save the ID there if you need it for direct lookup. You can also use tags to filter connections later or scope an agent session.
allowed_integrations controls what the user sees:
  • Multiple integrations — Connect UI shows a picker.
  • Single integration — Connect UI sends the user straight to its auth flow.
5

Add a connect button

In your frontend, load the Nango frontend SDK, fetch the session token from your backend, and open Connect UI:

Connect UI authorization flow

See the Frontend SDK reference for more options.To style the pre-built UI or build your own, see Customize Connect UI.
6

Handle the auth webhook

When authorization succeeds, Nango generates a connection ID. Save it alongside the matching record in your app for direct access to the connection.
  1. Add a POST endpoint in your backend and verify Nango’s webhook signature.
  2. In Environment Settings > Webhooks, enter the endpoint URL under Webhook URLs.
  3. Enable Auth: new connection webhooks. In your handler, use tags from the successful auth / creation event to match connectionId to the right record.
Confirm the target environment and webhook endpoint with the user. Check which destination slots are in use in the dashboard or with GET /environments/{environmentUuid}, which requires an Account API key with account:environments:read.To set the webhook URL and enable new connection events, call PATCH /environments/{environmentUuid} with an Account API key that has account:environments:update. If you need the environment UUID, list environments with account:environments:list.
Use secondary_url instead if the primary URL is already in use and the secondary slot is free. Omitted destinations and event settings keep their current values. Confirm with the user before replacing an existing destination.Management MCP currently doesn’t support setting this. Do it in the dashboard, with an account API key above, or ask the user to do it manually.
Webhook payload:
7

Add re-authorization

Credentials can become invalid when users revoke access, providers rotate refresh tokens, scopes change, or an app moves from testing to production. Re-authorization updates an existing connection’s credentials while preserving its data and config. Deleting and re-creating the connection wipes that data, therefore, prefer re-authorization.You can check the status of a connection with GET /connections/{connectionId}, for example, before rendering the integrations setup page for the user.
An invalid_credentials error means the connection failed credential refresh or validation — show an error state with a Reconnect button.To trigger re-authorization, use the same frontend flow as a new connection, but generate a reconnect session token on the backend. Pass the returned token to the Frontend SDK exactly like a normal session token. On success you’ll receive an auth webhook with operation: override.The connection keeps its connection ID. It also keeps its tags, unless the reconnect session passes non-empty tags key, which replaces the existing ones.
8

Run the flow

Test the auth flow from your app and verify a connection appears in the Connections tab. Failed attempts are inspectable in the Logs tab.
After the user runs the flow, confirm the connection was created. Use connections_list as shown in Test the authorization, or call GET /connections with the integration ID and the tags you set when you created the Connect session.
If the connection is missing, use the Management MCP log tools to debug. Start with logs_list_operations.
Match the operation to the time of the user’s attempt, then call logs_get_operation with the same environment and the operation’s id as operationId to read its messages.The REST API doesn’t expose logs, use the dashboard to debug.
Once the connection is established, use it across Nango with Agent sessions, Tools, Triggers, and Syncs.
Create a Connect session from your backend and share the returned data.connect_link with the user. Use an Environment API key with environment:connect_sessions:write. Include tags when you create the session. Connection tags link the new connection to records in your app. Choose IDs that match how your app finds connections and controls access, such as a user, organization, or workspace ID. When the user authorizes, the auth webhook includes your tags and the new connectionId. Use the tags to match the ID to the right record in your app. You can also use those tags to find the connection later or scope an agent session’s access.
Send the link to the user. Links expire after 30 minutes.