> ## Documentation Index
> Fetch the complete documentation index at: https://docs.membrane.agency/llms.txt
> Use this file to discover all available pages before exploring further.

# Connection UI Without the Front-End SDK

# Creating a Connection Without the Front-End SDK

> This guide explains how to create an integration connection in Membrane **without** using the front-end SDK. This is useful for backend-to-backend integrations, custom UIs, or automation scripts.\
> For the recommended process of creating a connection, check [Connection UI](/docs/ways-to-use-membrane/embedded-ui/connection-ui/custom-connection-ui).

## Overview

The connection process is initiated by making a request to the `/connect` endpoint of the API.\
This endpoint handles all authentication flows (OAuth2, OAuth1, client credentials, proxy) and manages the connection lifecycle.
After the connection process is completed (successfully or not), the user will be redirected to the `redirectUri` you specify in the parameters.

Opening the `/connect` endpoint should happen in your user's browser since many authentication flows require user interaction.

**High-level flow:**

1. Your backend (or custom UI) redirects the user to `/connect` with the required parameters.
2. The user is redirected (if needed) to the OAuth provider for authentication.
3. After authentication, Membrane redirects the user (or the flow) to your specified `redirectUri` with the result.
4. Your backend receives the result and can proceed accordingly.

***

## Constructing the Request

### Endpoint

```http theme={null}
POST /connect
Content-Type: application/json
```

### Parameters

You can send parameters either as query parameters or in a JSON-stringified `payload` parameter in the body of a POST request (recommended).

* `integrationId` or `integrationKey`: The integration to connect.
* `connectorId` or `connectorKey`: A connector to connect directly (no integration required).
* `externalAppId` or `externalAppKey`: An external app to connect directly.
* `input`: Object with connection-specific input (may be empty for some integrations). If passed through query, this value should be JSON-stringified.
* `connectionId`: To re-authenticate or update an existing connection in place. Without it, every completed flow creates a new connection.
* `name`: Name for the connection.
* `authOptionKey`: For integrations with multiple auth options.
* `customState`: Custom string to persist through the flow.
* `token`: JWT that authenticates the tenant workspace initiating the connection (See [Authentication](/docs/how-membrane-works/authentication)).
* `redirectUri`: **URL to which the result will be sent (your backend endpoint).**

### Example Request

This is an example HTML form that submits a correctly formatted connection request.

```html theme={null}
<form method="POST" action="https://api.getmembrane.com/connect" enctype="application/x-www-form-urlencoded">
  <input
    type="hidden"
    name="payload"
    value='{"integrationId":"your-integration-id","input":{"apiKey":"user-api-key"},"redirectUri":"https://your-backend.com/integration/callback"}'
  />
  <button type="submit">Connect</button>
</form>
```

```curl --location 'https://api.getmembrane.com/connect?integrationId=your-integration-id' \ theme={null}
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'payload={
    "input":{"apiKey":"user-api-key"},
    "authOptionKey": "",
    "redirectUri":"https://your-backend.com/integration/callback"
}'
```

### Parameters Schema

To understand which parameters are required to create a connection, see the [Custom Connection UI](/docs/ways-to-use-membrane/embedded-ui/connection-ui/custom-connection-ui).

## Connection Flow

* If the integration uses OAuth, the user will be redirected to the provider for authentication.
* After authentication, Membrane will redirect the user to the `redirectUri` you provided.
* If the integration uses client credentials or similar, the connection may be created immediately and the result sent to your `redirectUri`.

## Handling the Callback

Your backend should expose an endpoint matching the `redirectUri` you provided. Membrane will redirect to this URL with the following query parameters:

### On Success

* `connectionId`: The ID of the newly created or updated connection.

**Example:**

```
GET https://your-backend.com/integration/callback?connectionId=abc123
```

### On Error

* `error`: Error message.
* `errorData`: JSON-encoded error details.

**Example:**

```
GET https://your-backend.com/integration/callback?error=OAuth+failed&errorData=%7B...%7D
```