Flow

Start an authorization flow

POST
/integrations:connect

Creates a short-lived connect session for the authenticated caller and returns the provider authorization URL to open, plus the event stream that reports how the authorization ended. Both are this server's, which forwards them to Nango.

BearerAuth
headerAuthorizationBearer <JWT>

Admin token, API token issued via /api-tokens, or an OIDC JWT access token issued by the configured OIDC provider.

application/json
  1. body
integration*string

The integration to connect, e.g. google-mail.

scopes*array<string>

Scopes the caller needs.

Items1 <= items

Response Body

An authorization URL to open in the system browser, and the stream to watch.

application/json
  1. response
authorizeUrl*string

The provider's authorization URL, to open in the system browser. The client MUST append &ws_client_id=<id> taken from the event stream's connection_ack message before opening it.

eventsUrl*string

SSE stream to open, with the caller's credentials, BEFORE authorizeUrl. Each event's data is one of Nango's WebSocket messages, as JSON: {"message_type": "connection_ack", "ws_client_id"} first, then {"message_type": "success", "provider_config_key", "connection_id"} or {"message_type": "error", "error_type", "error_desc"}, after which the stream ends. Comment lines keep an idle stream open.

expireTime*string

When the session behind the URLs stops working.

Formatdate-time
Example Request
curl -X POST 'https://example.com/api/hub/integrations:connect' \  -H 'Content-Type: application/json' \  -d '{  "integration": "google-mail",  "scopes": [    "string"  ]}'
Example Response
{  "authorizeUrl": "http://localhost:3000/api/hub/integrations/auth/oauth/connect/google-mail?connect_session_token=abc123",  "eventsUrl": "http://localhost:3000/api/hub/integrations/auth/events",  "expireTime": "2019-08-24T14:15:22Z"}