Backend Integration

Your secret key must stay server-side. The SDK’s fetchSessionToken calls your endpoint; your endpoint forwards the request to the Connexease Session API with the secret key and returns the session payload to the SDK.

Browser (fetchSessionToken)
        │  POST /api/session (YOUR API)
        ▼
Your Backend
        │  POST https://public-api.gateway.connexease.com/api/v1/wa/embedded-signup/sessions
        │  Authorization: Bearer <CONNEXEASE_SECRET_KEY>
        ▼
Connexease Sessions API
        │
        └── response flows back up → reaches the SDK

The proxy path (/api/session here) is yours to choose — the SDK calls whatever you put in fetchSessionToken. Put your own authentication and authorization in front of it.

Don’t hardcode the API base URL. Read it from an environment variable with a production default so the same code works across local, staging, and production environments.

Dynamic API Base URL

The Gateway API base URL can be configured dynamically when the SDK is initialized:

import { GatewayEmbeddedSignup } from '@connexease/gateway-embedded-signup';

const apiBaseUrl = process.env.NEXT_PUBLIC_GATEWAY_API_BASE_URL;

const widget = GatewayEmbeddedSignup.init({
  publishableKey: process.env.NEXT_PUBLIC_GATEWAY_PUBLISHABLE_KEY!,
  ...(apiBaseUrl ? { apiBaseUrl } : {}),
});

Provide only the base URL:

https://your-gateway-api.example.com

The SDK appends the required Embedded Signup paths automatically:

/api/v1/wa/embedded-signup/preflight
/api/v1/wa/embedded-signup/sessions
/api/v1/wa/embedded-signup/connect

In the recommended production integration, fetchSessionToken calls your backend proxy. Therefore, the requests are routed as follows:

preflight + connect
SDK ─────────────────► NEXT_PUBLIC_GATEWAY_API_BASE_URL

sessions
SDK ─► /api/session ─► CONNEXEASE_API_BASE

NEXT_PUBLIC_GATEWAY_API_BASE_URL and CONNEXEASE_API_BASE should point to the same Gateway environment.If both values are omitted, the SDK and backend continue using the existing Connexease production API. Existing integrations do not need to provide these values.

NEXT_PUBLIC_GATEWAY_API_BASE_URL is safe to expose because it only contains the API base URL. The secret key must remain in the server-only CONNEXEASE_SECRET_KEY variable.The NEXT_PUBLIC_ prefix is specific to Next.js. For Vite applications, use a public variable such as VITE_GATEWAY_API_BASE_URL.

Node.js / Express
FastAPI (Python)

import express from 'express';

const app = express();
app.use(express.json());

const CONNEXEASE_SECRET_KEY =
  process.env.CONNEXEASE_SECRET_KEY;

const CONNEXEASE_API_BASE = (
  process.env.CONNEXEASE_API_BASE ??
  'https://public-api.gateway.connexease.com'
).replace(/\/+$/, '');

const SESSIONS_API =
  `${CONNEXEASE_API_BASE}/api/v1/wa/embedded-signup/sessions`;

app.post('/api/session', async (req, res) => {
  // Authenticate the caller here using your own authentication.

  if (!CONNEXEASE_SECRET_KEY) {
    return res.status(500).json({
      error: 'CONNEXEASE_SECRET_KEY is not configured',
    });
  }

  try {
    const upstream = await fetch(SESSIONS_API, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${CONNEXEASE_SECRET_KEY}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
    });

    const data = await upstream.json();

    // Preserve the upstream status and error body.
    if (!upstream.ok) {
      return res.status(upstream.status).json(data);
    }

    // Connexease wraps the response as:
    // { data: {...}, isSuccess: true }
    //
    // fetchSessionToken must receive the inner session object.
    return res.json(data.data ?? data);
  } catch (err) {
    return res.status(500).json({
      error: 'Failed to fetch session',
    });
  }
});

app.listen(3000);

import os
import httpx
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse

app = FastAPI()

CONNEXEASE_SECRET_KEY = os.getenv(
    "CONNEXEASE_SECRET_KEY"
)

CONNEXEASE_API_BASE = os.getenv(
    "CONNEXEASE_API_BASE",
    "https://public-api.gateway.connexease.com",
).rstrip("/")

SESSIONS_API = (
    f"{CONNEXEASE_API_BASE}"
    "/api/v1/wa/embedded-signup/sessions"
)

@app.post("/api/session")
async def create_session():
    # Authenticate the caller here using your own authentication.

    if not CONNEXEASE_SECRET_KEY:
        raise HTTPException(
            status_code=500,
            detail="CONNEXEASE_SECRET_KEY is not configured",
        )

    try:
        async with httpx.AsyncClient(timeout=10.0) as client:
            upstream = await client.post(
                SESSIONS_API,
                headers={
                    "Authorization": (
                        f"Bearer {CONNEXEASE_SECRET_KEY}"
                    ),
                    "Content-Type": "application/json",
                    "Accept": "application/json",
                },
                json={},
            )
    except httpx.RequestError:
        raise HTTPException(
            status_code=500,
            detail="Failed to fetch session",
        )

    data = upstream.json()

    # Preserve the upstream status and error body.
    if upstream.status_code >= 400:
        return JSONResponse(
            status_code=upstream.status_code,
            content=data,
        )

    # Connexease wraps the response as:
    # { "data": {...}, "isSuccess": true }
    #
    # fetchSessionToken must receive the inner session object.
    return data.get("data", data)

On success, your proxy must return the inner session object from data. You do not need to rename the compact gh, wv, pt, li, and bn fields because the SDK decodes them automatically.On failure, preserve the upstream HTTP status and error body. Your frontend’s fetchSessionToken can then throw the returned error so the SDK can display its error modal and deliver the failure through onError.

.env:

# Browser-side SDK configuration
NEXT_PUBLIC_GATEWAY_PUBLISHABLE_KEY=pb_xxxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_GATEWAY_API_BASE_URL=https://your-gateway-api.example.com

# Server-side session proxy configuration
CONNEXEASE_SECRET_KEY=sk_xxxxxxxxxxxxxxxxxxxxxx
CONNEXEASE_API_BASE=https://your-gateway-api.example.com

NEXT_PUBLIC_GATEWAY_API_BASE_URL and CONNEXEASE_API_BASE are optional. When omitted, they default to the existing Connexease production API.Provide only the base URL. Do not append /api/v1/wa/embedded-signup or an individual endpoint path.

Never prefix the secret key variable with NEXT_PUBLIC_, VITE_, or another framework-specific public prefix. CONNEXEASE_SECRET_KEY must never be included in the browser bundle.

Getting Started

Guides

Dynamic API Base URL

​Dynamic API Base URL

Dynamic API Base URL