Connect Sessions API

A connect session is a short-lived token (30 minutes) that you create server-side and pass to your frontend to initialize the Connect UI. The session encodes which end user is authenticating, which integrations they can connect to, and any connection defaults. This design keeps your secret key off the frontend: your server mints a session token and the browser only ever sees the short-lived token.

All API requests require a secret key passed as a Bearer token. You can find your secret key in the Settings section of the Nango dashboard.

Create a session

curl --request POST \
  --url https://api.nango.dev/connect/sessions \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "end_user": {
      "id": "user-123",
      "email": "alice@example.com",
      "display_name": "Alice"
    },
    "allowed_integrations": ["slack-production", "github-prod"],
    "tags": {
      "end_user_id": "user-123",
      "end_user_email": "alice@example.com",
      "organization_id": "org-456"
    }
  }'

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

const { data } = await nango.createConnectSession({
  end_user: {
    id: 'user-123',
    email: 'alice@example.com',
    display_name: 'Alice'
  },
  allowed_integrations: ['slack-production', 'github-prod'],
  tags: {
    end_user_id: 'user-123',
    end_user_email: 'alice@example.com',
    organization_id: 'org-456'
  }
});

// data.token is passed to your frontend
const sessionToken = data.token;

POST /connect/sessions Creates a new connect session. The session expires after 30 minutes. Pass the returned token to the Connect UI in your frontend.

Tags you set on the session are copied onto the connection when the user completes auth. They also appear in auth webhooks, making it easy to identify which user connected.

Request body

object

The end user who is authenticating. Required unless you provide top-level tags.

Hide properties

string

required

Your internal user ID. This is used to associate the resulting connection with a specific user.

string

User’s email address. Shown in the Nango dashboard.

string

User’s display name. Shown in the Nango dashboard.

object

The organization the end user belongs to.

Show properties

string

required

Your internal organization ID.

string

Organization display name.

string[]

Limit which integrations the user can connect to. If omitted, all integrations in your environment are available. Each entry is an integration unique_key.

object

Per-integration defaults applied when the user connects. Keys are integration unique_keys.

Show properties

string

Override the default OAuth scopes for this integration.

object

Extra query parameters to append to the OAuth authorization URL.

object

Connection-level config passed to the provider (e.g. subdomain, instance URL). Accepts oauth_scopes_override and any provider-specific fields.

object

Key-value tags copied onto the resulting connection. Common keys: end_user_id, end_user_email, organization_id. You can also add custom keys. When tags is provided at the top level, end_user becomes optional.

object

Per-integration Connect UI overrides. Keys are integration unique_keys.

Show properties

string

Override the documentation URL shown in the Connect UI for this integration.

Response

object

Hide properties

string

required

The session token to pass to the Connect UI. Valid for 30 minutes.

string

required

A ready-to-use Connect UI URL you can redirect users to directly, if you prefer not to embed the UI.

string

required

ISO 8601 timestamp when this session expires.

Example response

{
  "data": {
    "token": "nango_session_tok_abc123def456",
    "connect_link": "https://connect.nango.dev?session_token=nango_session_tok_abc123def456",
    "expires_at": "2024-01-15T11:00:00.000Z"
  }
}

Using the session token in your frontend

After you receive the token, initialize the Connect UI on your frontend with it:

Frontend (React example)

import { useNango } from '@nangohq/react';

function ConnectButton({ sessionToken }: { sessionToken: string }) {
  const nango = useNango();

  const handleConnect = () => {
    nango.openConnectUI({
      sessionToken,
      onEvent: (event) => {
        if (event.type === 'close') {
          console.log('Connect UI closed');
        }
        if (event.type === 'connect') {
          console.log('User connected:', event.payload.connectionId);
        }
      }
    });
  };

  return <button onClick={handleConnect}>Connect your apps</button>;
}

Create a reconnect session

curl --request POST \
  --url https://api.nango.dev/connect/sessions/reconnect \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "connection_id": "user-123",
    "integration_id": "slack-production",
    "end_user": {
      "id": "user-123",
      "email": "alice@example.com"
    }
  }'

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

const { data } = await nango.createReconnectSession({
  connection_id: 'user-123',
  integration_id: 'slack-production',
  end_user: {
    id: 'user-123',
    email: 'alice@example.com'
  }
});

const sessionToken = data.token;

POST /connect/sessions/reconnect Creates a session specifically for re-authenticating an existing connection. Use this when a connection’s credentials have expired or been revoked and you need the user to re-authorize. The resulting session opens the Connect UI pre-scoped to the specific connection being repaired, rather than allowing the user to choose any integration.

Request body

string

required

The ID of the existing connection to reconnect.

string

required

The unique key of the integration the connection belongs to.

object

The end user performing the reconnect.

Show properties

string

required

Your internal user ID.

string

User’s email address.

string

User’s display name.

object

Organization the end user belongs to.

Show properties

string

required

Your internal organization ID.

string

Organization display name.

object

Per-integration defaults to apply during reconnect. Same shape as Create a session.

object

Tags to apply or update on the connection when reconnect completes.

object

Per-integration Connect UI overrides. Same shape as Create a session.

Response

object

Hide properties

string

required

The reconnect session token to pass to the Connect UI.

string

required

A ready-to-use Connect UI URL for the reconnect flow.

string

required

ISO 8601 timestamp when this session expires (30 minutes from creation).

Example response

{
  "data": {
    "token": "nango_session_tok_reconnect789xyz",
    "connect_link": "https://connect.nango.dev?session_token=nango_session_tok_reconnect789xyz",
    "expires_at": "2024-01-15T11:00:00.000Z"
  }
}

Get a session

curl --request GET \
  --url https://api.nango.dev/connect/session \
  --header 'Authorization: Bearer <SESSION_TOKEN>'

GET /connect/session Retrieves the details of a connect session. Authenticate this request with the session token (not your secret key) as the Bearer token. This endpoint is primarily used by the Connect UI itself to load session configuration. You generally do not need to call it directly.

Headers

string

required

Bearer <SESSION_TOKEN> — the connect session token returned by Create a session.

Response

object

Hide properties

string[]

The integrations the user is allowed to connect to.

object

Per-integration defaults configured on the session.

object | null

The end user associated with this session.

boolean

Whether this is a reconnect session.

object

Connect UI appearance settings configured for your environment.

Example response

{
  "data": {
    "allowed_integrations": ["slack-production", "github-prod"],
    "integrations_config_defaults": {},
    "endUser": {
      "id": "user-123",
      "email": "alice@example.com",
      "display_name": "Alice"
    },
    "isReconnecting": false,
    "connectUISettings": {
      "title": "Connect your apps",
      "primaryColor": "#241c24"
    }
  }
}

Delete a session

curl --request DELETE \
  --url https://api.nango.dev/connect/session \
  --header 'Authorization: Bearer <SESSION_TOKEN>'

DELETE /connect/session Immediately invalidates a connect session. The session token can no longer be used to open the Connect UI. Use this if the user cancels the flow on your side before completing auth and you want to clean up.

Headers

string

required

Bearer <SESSION_TOKEN> — the connect session token to invalidate.

Response

Returns 204 No Content on success.

Security and expiry

Session tokens are short-lived (30 minutes) but grant the ability to create connections in your environment. Treat them like sensitive credentials.

Never expose your secret key to the browser. Always create sessions server-side and pass only the token to your frontend.
Sessions expire after 30 minutes. If a user takes longer than that to complete the flow, create a new session.
If you want to invalidate a session early (e.g. user logs out), call Delete a session.
Sessions are single-environment: a token from your production environment cannot be used with your development environment’s Connect UI.

Overview

Integrations & Connections

Functions & Proxy

SDKs

Connect Sessions API

Create a session

Request body

Response

Using the session token in your frontend

Create a reconnect session

Request body

Response

Get a session

Headers

Response

Delete a session

Headers

Response

Security and expiry

​Create a session

​Request body

​Response

​Using the session token in your frontend

​Create a reconnect session

​Request body

​Response

​Get a session

​Headers

​Response

​Delete a session

​Headers

​Response

​Security and expiry

Create a session

Request body

Response

Using the session token in your frontend

Create a reconnect session

Request body

Response

Get a session

Headers

Response

Delete a session

Headers

Response

Security and expiry