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": "[email protected]",
      "display_name": "Alice"
    },
    "allowed_integrations": ["slack-production", "github-prod"],
    "tags": {
      "end_user_id": "user-123",
      "end_user_email": "[email protected]",
      "organization_id": "org-456"
    }
  }'

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

end_user

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.

display_name

string

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

organization

object

The organization the end user belongs to.

Show properties

string

required

Your internal organization ID.

display_name

string

Organization display name.

allowed_integrations

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.

integrations_config_defaults

object

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

Show properties

user_scopes

string

Override the default OAuth scopes for this integration.

authorization_params

object

Extra query parameters to append to the OAuth authorization URL.

connection_config

object

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

Response

data

object

Hide properties

token

string

required

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

connect_link

string

required

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

expires_at

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": "[email protected]"
    }
  }'

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

connection_id

string

required

The ID of the existing connection to reconnect.

integration_id

string

required

The unique key of the integration the connection belongs to.

end_user

object

The end user performing the reconnect.

Show properties

string

required

Your internal user ID.

string

User’s email address.

display_name

string

User’s display name.

organization

object

Organization the end user belongs to.

Show properties

string

required

Your internal organization ID.

display_name

string

Organization display name.

integrations_config_defaults

object

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

Response

data

object

Hide properties

token

string

required

The reconnect session token to pass to the Connect UI.

connect_link

string

required

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

expires_at

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

Authorization

string

required

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

Response

data

object

Hide properties

allowed_integrations

string[]

The integrations the user is allowed to connect to.

integrations_config_defaults

object

Per-integration defaults configured on the session.

endUser

object | null

The end user associated with this session.

isReconnecting

boolean

Whether this is a reconnect session.

connectUISettings

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": "[email protected]",
      "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

Authorization

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

Build docs developers (and LLMs) love

Overview

Integrations & Connections

Functions & Proxy

SDKs

​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

Build docs developers (and LLMs) love

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