Skip to main content
Pre-requisite: complete the Configuration guide.
Tags are small key/value strings you can attach to a connect session. Nango copies them to the resulting connection and includes them in auth webhooks.

​
Why tags exist

Nango uses random UUIDs as connection IDs. This means there is no built-in way to tie a Nango connection back to a user, organization, or any other entity in your system. Tags solve this: they are the bridge between a Nango connection and the entities it belongs to in your application. Their primary purpose is attribution. When a user completes an auth flow, Nango sends a success webhook containing the tags you set when creating the connect session. This lets you reconcile the webhook with the right user/org/entity on your side and store the resulting connectionId against it. Beyond attribution, tags are also useful for:
  • Filtering connections via the API (e.g. list all connections for organization_id = org_123)
  • Routing webhooks or background jobs based on connection context
  • Navigating the Nango Dashboard — all tags are visible on the Connections pages.
Most apps start with these tags:
  • end_user_id
  • end_user_email
  • organization_id
Then add whatever additional routing identifiers you need (e.g. workspace_id, project_id, plan). Tags are intentionally flexible so you can model your own tenant/user/workspace structure without being constrained to a fixed schema.
Tags are designed for identifiers and routing metadata. Avoid putting secrets or large/free-form payloads in tags.
This guide extends the Implement API Auth flow.

​
1. Add tags when creating a Connect session

When requesting a new Connect session token from Nango, pass a tags object: 
import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: process.env['<NANGO-SECRET-KEY>'] });

api.post('/sessionToken', async (req, res) => {
  const { data } = await nango.createConnectSession({
    tags: {
      end_user_id: '<END-USER-ID>',
      end_user_email: '<END-USER-EMAIL>',
      organization_id: '<ORGANIZATION-ID>'
    },
    allowed_integrations: ['<INTEGRATION-ID>']
  });

  res.status(200).send({ sessionToken: data.token });
});

​
2. Read tags from the auth webhook

These tags will appear in successful auth webhooks sent by Nango: 
{
    "type": "auth",
    "operation": "creation",
    "success": true,
    "connectionId": "<CONNECTION-ID>",
    "tags": {
      "end_user_id": "<END-USER-ID>",
      "end_user_email": "<END-USER-EMAIL>",
      "organization_id": "<ORGANIZATION-ID>"
    },
    ...
}
Use these values to reconcile the generated connectionId with the user/org/workspace that initiated the flow in your application.

​
3. Read tags from the connection

Nango also stores these tags on the connection itself. 
import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });
const connection = await nango.getConnection('<INTEGRATION-ID>', '<CONNECTION-ID>');

console.log(connection.tags);

​
4. Filter connections by tags

You can filter connections by tags when listing connections: 
import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });

const { connections } = await nango.listConnections({
  tags: {
    end_user_id: '<END-USER-ID>',
    end_user_email: '<END-USER-EMAIL>',
    organization_id: '<ORGANIZATION-ID>'
  },
  limit: 100
});

console.log(connections);
Example response: 
{
  "connections": [
    {
      "id": 1,
      "connection_id": "<CONNECTION-ID>",
      "provider": "<PROVIDER-KEY>",
      "provider_config_key": "<INTEGRATION-ID>",
      "created": "2026-01-01T00:00:00.000Z",
      "metadata": null,
      "tags": {
        "end_user_id": "<END-USER-ID>",
        "end_user_email": "<END-USER-EMAIL>",
        "organization_id": "<ORGANIZATION-ID>"
      },
      "errors": []
    }
  ]
}
Filtering uses an AND match: a connection must contain all provided tag keys and values.

​
5. Update tags on an existing connection (optional)

If you need to update tags after a connection is created, patch the connection: 
import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });

await nango.patchConnection(
  {
    connectionId: '<CONNECTION-ID>',
    provider_config_key: '<INTEGRATION-ID>'
  },
  {
    tags: {
      end_user_id: '<END-USER-ID>',
      end_user_email: '<END-USER-EMAIL>',
      organization_id: '<ORGANIZATION-ID>',
      environment: '<ENVIRONMENT>'
    }
  }
);
Updating tags replaces the whole tag object. If you want to add or remove a single tag, fetch the current connection first, merge locally, then patch.

​
6. Special keys

Two tag keys receive special treatment in the Nango dashboard:
  • end_user_display_name — shown instead of the connection ID in the connections list, making it easier to identify who a connection belongs to.
  • end_user_email — shown alongside end_user_display_name in the connections list. The domain from the email address is also used to display the end user’s company logo on the connection detail page.

​
Validation rules

  • end_user_email: must be a valid email address (e.g. user@example.com).
Tag keys are lowercased, so End_User_Email and end_user_email are treated as the same key.

​
7. Limitations and rules

The tags have several limitations:
  • keys are automatically lowercased
  • keys are case-insensitive (duplicate keys after normalization are rejected)
  • keys must start with a letter and contain only alphanumerics, underscores, hyphens, periods, or slashes
  • keys can be up-to 64 characters long
  • only 10 tag keys per connection are allowed
  • values must be non-empty strings up to 255 characters long