Skip to main content
A tenant defines whose connected accounts an agent can use. For example, one session can use a salesperson’s Gmail and their organization’s shared Salesforce connection. When you create a session, select connections by tag or pin them by ID. Nango resolves one connection per matching integration and uses it for that session’s tool calls. Enable nango_create_connection to let the agent ask the user to connect an integration during the session. Connection tags are key-value pairs you attach to a connection. Scope a session using whatever identifiers fit your app’s data model, such as a user ID, team ID, or workspace ID. Set tenant.connections.any to a list of tag selectors. Nango uses AND between tags in the same selector and OR between selectors. You can use up to 10 selectors. In this example, a connection matches if it has both organization_id: acme and workspace: marketing, or if its user_id is 27382.

Resolving ambiguity

If the selectors match two or more connections on the same integration, there is no way to tell which one the session should use. Creation fails with ambiguous_connections, and no session is created:
There are two ways to resolve this:
  1. Add tags to the selector until it matches exactly one connection per integration.
  2. Pin one of the matched connections for that integration:
When you combine tags and pins, a pin must be one of the connections the selectors matched, or creation fails with pinned_connection_not_matched.

Pin connections

Use pinned when you already know the exact connection to use for an integration:
You can only use one pin per integration. Pinning a connection that does not exist fails with unknown_pinned_connection.

Integrations without a connection

A missing connection does not block session creation. The integration appears in the toolset as connected: false, and calls to its tools return a not-connected error. If nango_create_connection is disabled, the error tells the agent to notify the user and continue with its available tools. If enabled, it directs the agent to fetch a connect link for the user so they can connect the integration.