Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nangohq/nango/llms.txt

Use this file to discover all available pages before exploring further.

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"
    }
  }'
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.
​
organization
object
The organization the end user belongs to.
​
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.
​
tags
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.
​
overrides
object
Per-integration Connect UI overrides. Keys are integration unique_keys.

​
Response

​
data
object
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"
    }
  }'
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.
​
organization
object
Organization the end user belongs to.
​
integrations_config_defaults
object
Per-integration defaults to apply during reconnect. Same shape as Create a session.
​
tags
object
Tags to apply or update on the connection when reconnect completes.
​
overrides
object
Per-integration Connect UI overrides. Same shape as Create a session.

​
Response

​
data
object
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
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

​
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.